CD Ware Multimedia 1995 May

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / DATABASE / BILDR22C.ZIP / LIBS87.DOC < prev next >

Wrap

Text File | 1994-10-27 | 151.2 KB | 6,373 lines

Aeolus Software Clipper Function Library COPYRIGHT (c) 1992,1993 by Aeolus Software All rights reserved. FUNCTION LIBRARY REFERENCE GUIDE Aeolus Software P.O. Box 11915 St. Paul, MN 55111-0915 Mark H. Kania, CIS# 76270,2436 TABLE OF CONTENTS Conventions..............................................1 Procedure and Function Summary...........................2 ASC2BIN..................................................8 ADD_REC..................................................9 ASK......................................................10 APOP.....................................................11 ^^ BETWEEN..................................................13 BROWSER..................................................14 CENTER...................................................15 CHGDIR...................................................16 * ++ CHGDSK...................................................17 * ++ CHKCHR...................................................18 ++ CKPRTR...................................................20 CRSR_STATE...............................................21 * ++ DBCHANGED................................................22 ++ DBPUBL...................................................23 DBREPL...................................................24 DBSTATE..................................................25 ++ DBSTOR...................................................26 DEC2HEX..................................................27 ++ DRVTST...................................................28 * ++ DUPCHK...................................................29 ++ EDT_MEMO.................................................31 ++ ERRTONE..................................................32 ^^ ETC......................................................33 ++ FEOF.....................................................34 FGETS....................................................35 FGETSR...................................................36 ++ FIL_LOCK.................................................37 FLD_REPL.................................................38 GEN_MAINT................................................39 ^^ GENVLD...................................................43 ++ GOT......................................................44 || HEX2DEC..................................................46 ++ IN_CANADA................................................47 ++ IN_USA...................................................48 ++ INFILE...................................................49 ++ INPATH...................................................50 ++ ISEEK....................................................51 LSIDE....................................................52 || MAKE_EMPTY...............................................53 || MAKDIR...................................................54 * ++ MAXHNDLS.................................................55 MEM_HELP.................................................56 ++ MEMFUNC..................................................57 ++ MESSAGE..................................................58 MSGBOX...................................................59 ^^ NET_USE..................................................61 || TABLE OF CONTENTS NOT_REQ..................................................62 ++ NUMERIC..................................................63 OPEN_FIL.................................................64 PADC.....................................................65 PADL.....................................................66 PADR.....................................................67 PCKVLD...................................................68 ++ PLIST....................................................70 POP......................................................74 ^^ POP_KEY..................................................77 PUBL_COLO................................................78 REC_LOCK.................................................79 REL_MAINT................................................80 ^^ REQ......................................................83 ++ RGHT_JST.................................................84 ++ RSIDE....................................................85 || SAVE_IT..................................................86 SETMSGLIN................................................88 ++ SHADOW...................................................89 SHOW_MEMO................................................90 ++ SHOW_TXT.................................................91 ++ TEXTVIEW.................................................93 ++ THERMOMETR...............................................96 TIMEOUT..................................................97 * ++ TOTALKEYON/TOTALKEYOFF...................................101 || WAITKEY..................................................102 WINPOP...................................................103 WINPUSH..................................................104 * These functions are located in BLDRASM.LIB. WARNING: Do NOT link BLDRASM into an overlay as some of the routines take over system interrupts and if these routines are in an overlay your computer will lock up. That is why it is in a separate LIB. ++ These functions are new to BUILDER.LIB v2.0. ^^ These functions are updated from the last release. || These functions are copied from the book "Programming in Clipper" 2nd Edition by Stephen J. Straley (use by permis- sion) I would also like to highly recommend Steves's new book "Clip- per Power Tools" from Sirius Software I comes with a diskette of indispensable Clipper routines. The Aeolus Procedure and Function Library Reference Manual Conventions used in this guide: <expC>: A character expression <expL>: A logical expression (i.e. .t. or .f.) <expD>: A date expression <expN>: A numeric expression, a number or calculation <expA>: An array name <exp>: An expression that may be of any type <expB>: A binary expression. Parameters notated inside square brackets ([]) are optional par- ameters, defaults will be given where applicable. Many BUILDER library procedures and functions use one or more system wide memory variables. These variables must be declared in the initialization of ALL programs which use this library. Fortunately the BUILDER code generator does this for you, but if you would like to code from scratch and use the library be sure these variables exist before using any library proce- dures/functions: SYSDEL - Logical if set to true tells the library that SET DELETED is ON. If false OFF. XPLODE - Logical if set to true tells the WINPUSH() function to explode your windows onto the screen. If false windows 'pop' onto screen. MSG_LN - Numeric, the line number where messages are displayed, should always be set to 24. NETWORK - Logical if set to true opens files in shared mode and locks records before writing to files. If false files are opened EXCLUSIVE. The 15 color variables - See the PUBL_COLO procedure for their names. <1> The Aeolus Procedure and Function Library Reference Manual Alphabetical Proc/Func summary ASC2BIN(<expC>) Converts ASCII control indicators to control characters. *ADD_REC(<expN>) Adds a blank .DBF record. ASK(<expC1>,<expC2>,<expN1>,<expN2>[,<expN3>][,<expC3>] ; [,<expC4>]) Prompt function. APOP(<expN1>,<expN2>,<expN3>,<expN4>,<expA>,<expN5>,<expC1>[<exp- C2>][,<expC3>]) Choose multiple menu items from array. BETWEEN(<exp1>,<exp2>,<exp3>) Evaluates if expression 1 is greater than and equal to expres- sion 2 and less than and equal to expression 3 BROWSER WITH <expN1>,<expN2>,<expN3>,<expN4>[,<expC>][,<expN5>][,<expN6>] Sets up window to browse a database CENTER(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>]) Centers text on the screen or within a window. CALL CHGDIR WITH <expC> Changes the DOS default directory. CALL CHGDSK WITH <expC> Changes the DOS default drive. VALID CHKCHR(<expC1>,<expC2>,<expN1>,<expN2>,<expN3>[,<expC3>]) VALID, tests if keyed input is in <expC1>. CKPRTR(<expN>) Checks if parallel printer is available. CRSR_STATE() Returns true if a SET CURSOR ON is in effect, false if SET CURSOR OFF is in effect. DBCHANGED(<expC>) Returns true if database fields do not exactly match memory variables. DBPUBL WITH <expC> Creates public memory variables from database field variables. DBREPL WITH <expC> Replaces database field variables with memory variables. <2> The Aeolus Procedure and Function Library Reference Manual DBSTATE([<expC1>]) Returns all relevant database info in a string, sets back to a previous DBSTATE() also. DBSTOR WITH <expC> Stores database field variables to memory variables. DEC2HEX(<expN>) Returns a Hexadecimal string of the passed integer. CALL DRVTST WITH <expC1>,<expC2> Tests a disk drive and returns a DOS error code. VALID DUPCHK(<expC1>,<expC2>,<expN1>,<expC3>,<expN2>,<expN3>, ; <expN4>,<expL>,<expC4>) VALID function to test for a duplicate condition for the keyed input. EDT_MEMO(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>,<expC3>, ; <expC5>,<expC6>[,<expN5>][,<expL>] Either stand alone or VALID function to display/edit a Memo field inside a border. ERRTONE([<expN>]) Beep speaker with optional sounds. ETC(<expC>,<expN1>,<expN2>,<expN3>) Calculate estimated time to complete an iterative process. FEOF([<expL>]) Use when reading a .SDF file with FGETS(). FGETS(<expN>) Returns next record in a .SDF type file. FGETSR(<expN>) Returns the previous record in a .SDF type file. FIL_LOCK(<expN>) Locks a file for exclusive type activity. FLD_REPL WITH <expC1>,<expC2> Replace one database field in a shared or single user environment. *GEN_MAINT WITH ; <expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>[,<expN5>] ; [,<expN6>][,<expL>] Generic file maintenance. GENVLD(<expL1>,<expC1>,<expN1>,<expN2>,<expN3>,<expL2>[,<expC2>]) <3> The Aeolus Procedure and Function Library Reference Manual VALID generic function to test a user defined condition on a GET. GOT(<expC>,<expN1>,<expN2>) Get field data from a database record number and field number. HEX2DEC(<expC>) Converts a string of Hexadecimal characters to a numeric integer. IN_CANADA(<expC>) Returns true if the passed two byte string is a valid Canadian province code. IN_USA(<expC>) Returns true if the passed two byte string is a valid U.S. state code. INFILE(<expC1>,<expN1>,<expC2>,<expN2>,<expN3>,<expN4>,<expL> [,<expC3>]) VALID function to only force data entered into a GET field to be found in another file. INPATH(<expC1>[,<expC2>]) Returns the pathname where <expC1> is located. Checks directories listed in DOS environment variable PATH or <expC2> if passed. ISEEK(<exp>,<expC>,<expN>,<expL>) Locate a record in a database via an index. *LSIDE left arrow logic for drop down menu scrolling. CALL MAKDIR WITH <expC> Makes a DOS subdirectory. MAKE_EMPTY(<expC>) Create an empty memory variable based on the passed variable. *MAXHNDLS(<expN>) Tests system configuration for number of file handles. *MEM_HELP Procedure called when F1 key is pressed during when user is editing a Memo field through the EDT_MEMO() function. *MEMFUNC(<expN1>,<expN2>,<expN3>) Function executed on every key press while editing a Memo field through SHOW_MEMO or EDT_MEMO(). MESSAGE(<expC1>,<expN1>,<expN2>[,<expN3>][,<expC2>]) Display a screen message. <4> The Aeolus Procedure and Function Library Reference Manual MSGBOX(<expC1>[,<expC2>][,<expC3>][,<expC4>][,<expN1>] ; [,<expN2>][,<expN3>][,<expN4>]) Display a message box on the screen, optionally ask a ques- tion. *NET_USE(<expC1>,<expL>,<expN>,<expC2>) Network file open function. NOT_REQ(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>]) VALID function to force a GET field to be empty. NUMERIC(<expC>) Check a character string for any non-numeric characters. OPEN_FIL(<expC1>[,<expL1>][,<expC2>][,<expL2>]) All purpose file open routine. PADC(<expC1>,<expN>[,<expC2>]) Pad a character string to the middle, centering it. PADL(<expC1>,<expN>[,<expC2>]) Pad a character string to the left, right justify it. PADR(<expC1>,<expN>[,<expC2>]) Pad a character string to the right, left justify it. PCKVLD(<expC1>,<expN1>,<expN2>,<expL1>,<expC2>,<expL2> ; [,<expC3>][,<expC4>]) VALID function to force entry into a GET field to be in another database. Gives user a pick list of the nearest data to what was keyed. PLIST(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expN5>,<expC1>, ; <expC2>[,<expL1>][,<expC3>][,<expC4>][,<expC5>][,<expC6>]) New picklist window function. POP(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>[,<expL1>] ; [,<expC3>][,<expC4>][,<expC5>][,<expC6>]) Pick list window function. *PUBL_COLO Sets default color variables. *REC_LOCK(<expN>) Record lock function. REL_MAINT WITH <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ; <expC2>,<expC3>,<expC4>,<expN5>,<expN6> Child relation file maintenance. REQ(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>]) VALID function to force a GET field to not be empty. <5> The Aeolus Procedure and Function Library Reference Manual RGHT_JST([<expC>]) VALID function to right justify input to a GET field. *RSIDE right arrow logic for drop down menu scrolling. SAVE_IT(<expC1>,<expC2>,<expN>,<expC3>) All purpose file I/O routine. SETMSGLIN([<expC>]) Function to Get/Set the application message line. *SHADOW(<expN1>,<expN2>,<expN3>,<expN4>) Puts a shadow on a box. SHOW_MEMO WITH <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ; <expL>[,<expC2>][,<expN5>] Display/Edit a Memo field without a border or message line or title. SHOW_TXT(<exp>,<expN1>,<expN2>,<expN3>[,<expC>]) VALID function to display data after input from a GET. TEXTVIEW WITH <expN1>,<expN2>,<expN3>,<expN4>,<expC1>[,<expC2>] Display a text file. THERMOMETR(<expN1>,<expN2>,<expN3>,<expN4>) Creates a thermometer to show the progress of a routine. CALL TIMEOUT WITH <expB1>,<expB2>,<expC> Set up an application timeout if idle for a passed length of time. Also changes the cursor to a block if in insert mode and underline when not. *TOTALKEYON/TOTALKEYOFF Enables/Disables drop down menu right and left scrolling. WAITKEY([<expN>]) Works like INKEY(0) but allows SET KEY TO ...'s to be pro- cessed. WINPOP() Remove a window from the screen create with WINPUSH. WINPUSH(<expN1>,<expN2>,<expN3>,<expN4>[,<expL1>] ; [,<expL2>][,<expL3>][<expL4>]) Put a window on the screen, may be saved for later removal. * Procedures and functions preceded by an asterisk (*) are either dealt with entirely by BUILDER generated code or are called by another library function. You will probably never <6> The Aeolus Procedure and Function Library Reference Manual need to use these and are included only for the sake of completeness. <7> The Aeolus Procedure and Function Library Reference Manual ASC2BIN() Syntax: ASC2BIN(<expC>) Pass: <expC> string with control character expressions embedded. Returns: Character expression. The converted string. Description: The ASC2BIN() function converts a character expression that con- tains one or more caret (^) symbols followed by a character to it's 'control' or binary value. Use this function for creating printer control strings. For example : c=ASC2BIN("^A") && caps important ? asc(c) && would display 1 -- ASCII for && control A Sample: *********************************************** ** print a message on a laser printer in ** landscape using HP escape sequence prtrt="^[&l0O" && caret, left bracket (escape), && ampersand, lower case L, zero, && upper case O lndscp="^[&l1O" && caret, left bracket (escape), && ampersand, lower case L, one, && upper case O set print on ?? asc2bin(lndscp) && set printer to landscape ? "This text printed using landscape." ?? asc2bin(prtrt) && set printer back to portrait <8> The Aeolus Procedure and Function Library Reference Manual ADD_REC() Syntax: add_rec(<expN>) Pass: <expN> seconds until timeout, zero for no timeout. Returns: a logical expression. Description: Attempts to add a blank record to the currently selected data- base for timeout period of <expN> seconds. If a record cannot be added after the timeout period an error box is presented to try again, if No is selected, a logical false is returned. If <expN> is zero or not passed to the function, ADD_REC() will wait indefinitely. Comment: This function is called by the SAVE_IT() function therefore it should never need to be used by you in a program, use the SAVE_IT() function to do file I/O instead. It is included here only for completeness. <9> The Aeolus Procedure and Function Library Reference Manual ASK() Syntax: ASK(<expC1>,<expC2>,<expN1>,<expN2>[,<expN3>][,expC3][,<expC4>]) Pass: <expC1> prompt text. <expC2> list of acceptable input characters. <expN1> row for prompt. <expN2> column for prompt. <expN3> pad prompt to length. <expC3> alternate color. <expC4> "ESC" to allow ESC key. Returns: Character expression. The keyboard character pressed. Description: <expC1> will be displayed at row <expN1> and column <expN2>. ASK() will wait until any keyboard character contained in the list <expC2> is pressed. <expC2> may be passed in upper or lower case, ASK() does not distinguish. If you pass "YN" either a lower or upper case 'Y' key press will return an upper case "Y" from ASK(). Also if you pass "yn" either a lower or upper case 'Y'key press will return an upper case "Y". <expN3> spaces will be displayed before the message in <expC1> to clear previous text, optional. default is the length of <expC1>. <expC3> is color to display <expC1>. Default is current color. If <expC4> is equal to "ESC" then ASK() can be exited using the ESC key. If the ESC key is used to exit ASK() a null string will be passed to the calling procedure. The default is to not allow ESCaping. Sample: ***************************************************** ** display the question on line 24 column 0 and pad ** the text to 80 characters. Wait until a Y or N ** is pressed on the keyboard. answer=ask("Do You Wish to Continue? (Y/N)","YN",24,0,80) ** the character variable "answer" will equal either "Y" ** or "N" depending on what the key is pressed. <10> The Aeolus Procedure and Function Library Reference Manual APOP() Syntax: apop(<expN1>,<expN2>,<expN3>,<expN4>,<expA>,<expN5> ; [,<expC1>][,<expC2][,<expC3>]) Pass: <expN1> top left row. <expN2> top left column. <expN3> bottom right row. <expN4> bottom right column. <expA> array name (prefixed with @). <expN5> max element to show. <expC1> procedure name to execute. <expC2> alternate color choice. <expC3> alternate reverse color choice. Returns: Nothing. Description: The APOP() function will put a box on the screen using <expN1> through <expN4> as screen coordinates and allow you to scroll through elements 1 to <expN5> of the array <expA>. When a selection is made by pressing the 'T' key will Tag that element and display it bounded by bracket characters (« »). Pressing ENTER will either execute the procedure <expC1> or exit APOP(). <expC2> is an optional color value, <expC3> is an alternate reverse color option. Defaults for <expC2> and <expC3> are the current colors. Upon return from APOP() check the first character of each array element for chr(174) for tagged elements. Sample: ******************************************************** ** APOP() example code to allow the selection of multiple ** names from a list and then display the selected items. ** declare names[10] && declare array names[01]="Rosalind " && initialize array names[02]="Mark " names[03]="John " names[04]="Lisa " names[05]="Denise " names[06]="Jeff " names[07]="Frank " names[08]="Joe " names[09]="Cathy " names[10]="Jerry " ** call APOP() <11> The Aeolus Procedure and Function Library Reference Manual apop(05,05,13,18,@names,10,"PRT_NMES") ** the bracket character -chr(174)- is left on the array ** elements that have been selected, so if it is in the ** first character position, that element was selected by ** the user procedure prt_nmes set print on set console off for a=1 to 10 if left(names[a],1)=chr(174) ? trim(subs(names[a],2))+" was selected." endi next <12> The Aeolus Procedure and Function Library Reference Manual BETWEEN() Syntax: between(<exp1>,<exp2>,<exp3>) Pass: <exp1> value to test. <exp2> minimum value. <exp3> maximum value. Returns: a logical expression. Description: A logical true will be returned if <exp1> is greater than and equal to <exp2> and less than and equal to <exp3>. The argu- ments passed to the BETWEEN() function may be of type Character, Numeric or Date; however all three arguments must be the same data type. <13> The Aeolus Procedure and Function Library Reference Manual BROWSER Syntax: do browser with <expN1>,<expN2>,<expN3>,<expN4>[,<expC>] ; [,<expN5>][,<expN6>] Pass: <expN1> top left row. <expN2> top left column. <expN3> bottom right row. <expN4> bottom right column. <expC> key exception function name. <expN5> start field number. <expN6> end field number. Description: The BROWSER procedure will "browse" the currently selected data- base using the Clipper DBEDIT() function. <expN1> through <expN4> define the coordinates of the box that will be dis- played, <expC> is the user defined function executed on each key press. <expN5> and <expN6> are the start and end field numbers (i.e. the FCOUNT() number) to browse. If <expN5> is not passed the first field will be browsed. If <expN6> is not passed the <expN5>th through FCOUNT() fields will be browsed. For more information on using the <expC> user defined function consult your Clipper manual on the DBEDIT() function. <expC> is merely passed to DBEDIT() as the UDF for each key press. Sample: ****************************************************** ** BROWSER sample call ** select 0 use customer do browser with 5,3,17,73 ** this will put a box on the screen from row 5 column 3 to row ** 17 column 73 and browse all the fields in the database ** CUSTOMER. <14> The Aeolus Procedure and Function Library Reference Manual CENTER() Syntax: center(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2]) Pass: <expC1> message to display. <expN1> row to begin centering computation. <expN2> column to begin centering computation. <expN3> length for centering computation. <expC2> alternate color. Returns: Start column of centered text. Description: The CENTER() function displays <expC1> on row <expN1> column <expN2> centered within a width <expN3> wide. <expC2> is an alternate color choice. The default color is the current from the last SET COLOR TO ... statement. Sample: **************************************************** ** CENTER() function example ** ** put a box on the screen winpush(5,5,15,45) ** center text in the box center("Yoo Hoo, I'm Centered",7,16,29) inkey(0) ** remove box winpop() <15> The Aeolus Procedure and Function Library Reference Manual CHGDIR Syntax: call chgdir with <expC> Pass: <expC> - a DOS subdirectory name on the current drive. Returns: Nothing. Description: The CHGDIR assembly subroutine simply attempts to change to the subdirectory named in the passed parameter <expC>. No error checking is done and nothing is passed back as a return value. <16> The Aeolus Procedure and Function Library Reference Manual CHGDSK Syntax: call chgdsk with <expC> Pass: <expC> - A single byte of the disk drive letter to set as the new default drive. Returns: Nothing. Description: The CHGDSK assembly subroutine simply attempts to change the default DOS disk drive to the passed drive letter parameter <expC>. No error checking is done and nothing is passed back as a return value. <17> The Aeolus Procedure and Function Library Reference Manual CHKCHR() Syntax: chkchr(<expC1>,<expC2>,<expN1>,<expN2>,<expN3>,[<expC3>]) Pass: <expC1> - A list of allowable entry data into the GET. <expC2> - Error message on entry of non-allowable data. <expN1> - Row for error message to display. <expN2> - Column for error message display. <expN3> - Rightmost column for error message display. <expC3> - Optional color for error message. default WERR_CLR. Returns: A logical expression. Description: This function is designed to be use as a VALID function to a GET only. It will test if the data keyed into the GET is embedded in the <expC1> string. If it is the GET is allowed otherwise an error beep is sounded and the error message <expC2> is displayed at screen row <expN1> column <expN2> and will be padded or trun- cated to screen column <expN3>. If <expC3> is passed as a par- ameter the error message will be display using it as the color value otherwise the color contained in the public memory vari- able WERR_CLR will be used. Samples: ** QTYPE is a one byte variable with allowable values of 1, 2, or 3 ** only. Use CHKCHR() to force a 1, 2, or 3 into this field like ** this ... qtype=" " @ dr1+02,dc1+21 get qtype pict "9" valid ; chkchr("123","1, 2, 3 Only Allowed",dr2-1,dc1+2,dc2-2) set cursor on read set cursor off ** Same example, but allow QTYPE to be blank. Just add a ** space as an allowable character in the list! qtype=" " @ dr1+02,dc1+21 get qtype pict "9" valid ; chkchr(" 123","1, 2, 3 or Blank Only",dr2-1,dc1+2,dc2-2) set cursor on read set cursor off <18> The Aeolus Procedure and Function Library Reference Manual If QTYPE (or whatever field) is more than one character long, be sure to use a separator between allowable field values. ** QTYPE2 allowable values are "EA" for Each, "PK" for ** Package, or "WT" for Weight. ** You can use CHKCHR() in the following manner to ** force the field QTYPE2 to be one of these values... qtype2=" " @ dr1+02,dc1+21 get qtype2 pict "!!" valid ; chkchr("EA~PK~WT","Enter EA-Each, PK-Package, or WT-Weight", ; dr2-1,dc1+2,dc2-2) Note though that if the user entered "A~" or "~P" CHKCHR() would allow it. You may choose to use a separator that cannot be entered from the keyboard, however, I cannot foresee a user accidentally stumbling the tilde condition. <19> The Aeolus Procedure and Function Library Reference Manual CKPRTR() Syntax: ckprtr([<expN>]) Pass: nothing or 1, 1 if ESCaping is allowed. Returns: a logical expression. --DESCRIPTION: The CKPRTR() function returns a logical true if the Clipper ISP- RINTER() function returns a logical true. CKPRTR() displays an error box if ISPRINTER() returns false and checks the ISP- RINTER() function again after a key is pressed. You can see that an infinite loop will be created if the printer cannot be brought on-line, if <expN> is a value of one (1) then the ESC key will allow an exit from CKPRTR() when the printer is not operating and if ESCaped CKPRTR() will return false (.f.). --SAMPLE: ************************************************* ** CKPRTR() function example proc a_report set device to printer do while !eof() if !ckprtr(1) && check printer on each print line exit endi . print report commands . . enddo >>COMMENT: The CKPRTR() function will only work with parallel printers. <20> The Aeolus Procedure and Function Library Reference Manual CRSR_STATE Syntax: crsr_state() Pass: Nothing Returns: A logical value. Description: If the Clipper program currently has a SET CURSOR ON in effect the CRSR_STATE() function will return true (.T.). If a SET CUR- SOR OFF is in effect, false (.F.) is returned. This function is very useful when programming for Clipper SET KEY TO ... procedures. <21> The Aeolus Procedure and Function Library Reference Manual DBCHANGED() Syntax: dbchanged(<expC>) Pass: <expC> - Prefix character(s) to database field names for memory variables. Returns: A logical value. Description: The DBCHANGED() function returns true (.T.) if any of the data- base field values are different from the memory variables created with the exact same prefix character(s), otherwise false (.F.) is returned. See DBPUBL, DBSTOR <22> The Aeolus Procedure and Function Library Reference Manual DBPUBL Syntax: do dbpubl [with <expC>] Pass: Nothing or public variable prefix character(s). If nothing is passed, the default is "Q". Description: Dbpubl declares a public memory variable for each field variable in a database. The memory variables created will be prefixed by <expC>. If <expC> is not passed "Q" is assumed as the default. See DBREPL, DBSTOR and SAVE_IT(). Variables are only made PUBLIC and not initialized to any value therefore all variables will be set to .F. by Clipper at the completion of this procedure. Sample: *************************************************** ** DBPUBL example ** ** a database with the following structure is assumed ** ** FNAME Character 15 ** LNAME Character 20 ** ADDRESS Character 35 ** PHONE Character 10 ** select 0 use addrbook ** declares mfname,mlname,maddress,mphone as public do dbpubl with "M" Comment: <expC> should be kept as short as possible otherwise the unique- ness to your field variables can be lost, I suggest a length of one, two as an absolute maximum. <23> The Aeolus Procedure and Function Library Reference Manual DBREPL Syntax: do dbrepl [with <expC>] Pass: Nothing or variable prefix character(s). If nothing is passed, the default is "Q". Description: DBREPL replaces all the field variables in a record using memory variables that exactly the same names as the field variables except they are prefixed with <expC>. See DBPUBL, DBSTOR and SAVE_IT(). Sample: *************************************************** ** DBREPL example ** ** a database with the following structure is assumed ** ** FNAME Character 15 ** LNAME Character 20 ** ADDRESS Character 35 ** PHONE Character 10 ** select 0 use addrbook ** declares mfname,mlname,maddress,mphone as memory vars mfname="DENISE" mlname="JOHNSON" maddress="123 MAPLE ST" mphone="6125551234" appe blan && add a blank record do dbrepl with "M" && replace all field vars. Comment: <expC> should be kept as short as possible otherwise the unique- ness to your field variables can be lost, I suggest a length of one, two as an absolute maximum. <24> The Aeolus Procedure and Function Library Reference Manual DBSTATE() Syntax: dbstate([<expC>]) Pass: Nothing or a string returned from a previous DBSTATE() function call. Returns: A string of the complete state of the currently selected database. Select area, record number, index order number, filter expres- sion, all relation information. Description: DBSTATE() saves all the information possible for the currently selected work and returns it to the program in a single charac- ter string. Passing a string saved from a previous DBSTATE() call as <expC> will set the work area of that DBSTATE() string to the state it was in. This function is very useful when you want to preserve the cur- rent database conditions exactly but you also need to use the same database for another purpose. Sample: select a_database dbsav=dbstate() && save state of A_DATABASE ** change state of A_DATABASE set order to 3 set filter to the_field="A" set relation to go top select another dbstate(dbsav) && selects A_DATABASE and puts it in the && state it was in on the first DBSTATE() && call. <25> The Aeolus Procedure and Function Library Reference Manual DBSTOR Syntax: do dbstor [with <expC1>][,<expC2>] Pass: <expC1> prefix for memvars, default "Q". <expC2> nothing for data or "EMPTY" for empty values. Description: DBSTOR stores all the field variables in a record to memory variables with exactly the same names as the field variables variable except they are prefixed with <expC1>. If <expC2> is passed as "EMPTY" then all memory variables will be assigned as if the record were blank. See DBPUBL, DBREPL and SAVE_IT(). Sample: *************************************************** ** DBSTOR example ** ** a database with the following structure is assumed ** ** FNAME Character 15 ** LNAME Character 20 ** ADDRESS Character 35 ** PHONE Character 10 select 0 use addrbook ** declares mfname,mlname,maddress,mphone as public, you must ** do this in order to use DBSTOR do dbpubl with "M" do dbstor with "M","EMPTY" && create 'blank' vars clea @ 0,0 say "First Name" get mfname pict "@! @ 1,0 say " Last Name" get mlname pict "@!" @ 2,0 say " Address" get maddress pict "@! @ 3,0 say " Phone" get mphone pict "@R (999) 999-9999" read appe blan && add a blank record do dbrepl with "M" && replace all field vars. Comment: <expC> should be kept as short as possible otherwise the unique- ness to your field variables can be lost, I suggest a length of one, two as an absolute maximum. <26> The Aeolus Procedure and Function Library Reference Manual DEC2HEX() Syntax: dec2hex(<expN>) Pass: A numeric integer value. Returns: A character string of the hexadecimal value of the passed integer. Description: This function is the compliment to the HEX2DEC() function. If you have a need to convert numbers to hexadecimal, you will find this function useful. <27> The Aeolus Procedure and Function Library Reference Manual DRVTST Syntax: call drvtst with <expC1>,<expC2> Pass: <expC1> - The DOS drive letter to test. <expC2> - A place for DRVTST to put the return code. Returns: N - No error or 0-C to indicate the DOS error number that occurred while attempting to read from or write to the disk drive indicated as <expC1> Description: Use the DRVTST assembly subroutine tests the disk drive with the letter passed as <expC1>. This routine reads a disk sector then writes it back out to make sure the drive is usable. The return value is placed in <expC2> which must be at least one (1) byte in length BEFORE the call to DRVTST. The possible return values are: N - No error occurred 0 - Disk is Write Protected 1 - Cannot Access Disk Drive 2 - Drive Not Ready 3 - Unknown Error on Disk Drive 4 - Data Error Reading Drive 5 - General Error 5 6 - Seek Error on Disk Drive 7 - Unknown Disk Format 8 - Sector Not Found 9 - Printer Out of Paper?? A - Write Fault Reading Disk Drive B - Read Fault Error on Disk Drive C - General Failure Reading Disk Drive If some of the return values seem strange or out of place con- sult your DOS manual as that is where I found them. <28> The Aeolus Procedure and Function Library Reference Manual DUPCHK() Syntax: dupchk(<expC1>,<exp>,<expN1>,<expC2>,<expN2>,<expN3>,<expN4>, ; <expL>[,<expC3>]) Pass: <expC1> - either "A" to check of the Addition of a record will cause a duplicate, or "C" to check if Changing the record will cause a duplicate. <exp> - Key value to duplicate check. <expN1> - Index order number for duplicate check. <expC2> - Error message to display. <expN2> - Screen row to display error message. <expN3> - Screen column to display error message. <expN4> - Rightmost screen column to display error message. <expL> - GET is required (.T.) or may be blank (.F.). <expC3> - Color to display error message, default is WERR_CLR. Returns: A logical value, this function is to be used as a VALID for a GET only. Description: The DUPCHK() valid function tests the value entered into a GET field to see if it will cause a duplicate record when saved. This function is useful when two indexes are maintained on a single database and both keys must not contain duplicates. If you are using GEN_MAINT or REL_MAINT pass G_FUNC as <expC1> as it will contain "A" on Adds and "C" on changes. The 2nd parameter (<exp>) should (almost has to) include the GET memvar somewhere within it. Sample: Let's say you have a file maintenance routine of customer infor- mation. This file has a primary key of customer number which is a unique number your company assigns to each customer. One of the fields in your customer information file is a serial number which is the serial number of the product your company sold them. Since no two customers can possess the same product at the same time you would like to make sure all the product serial numbers entered into the database are unique. This is a situation where DUPCHK() could be used effectively. Let's now assume the system you designed contains a file called CUSTOMER containing the customer information and index order number three (3) is on the a field called SERIAL_NBR. <29> The Aeolus Procedure and Function Library Reference Manual You could program DUPCHK() to make sure inventory items are never keyed duplicated in the customer file as follows: Other file maintenance GETs. . . . @ fmr1+05,fmc1+22 get &g_pfx.serial_nbr valid ; dupchk(g_func,"CUSTOMER",&g_pfx.serial_nbr,3, ; "ERROR: Serial Number Already in Use",fmr2-1,fmc1+2,fmc2-2,.t.) The DUPCHK() Valid above would force entry into the SERIAL_NBR field to be unique. The error message would be displayed if the field were or would create a duplicate. Because the ninth par- ameter is set to true (.T.) the error message would display if the user attempted to leave the field blank. An error beep accompanies the error message display and the user is not allowed to proceed to the next field in the GET stream. <30> The Aeolus Procedure and Function Library Reference Manual EDT_MEMO() Syntax: edt_memo(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2>, ; <expC3>,<expC4>,<expC5>[,<expN5>][,<expL1>][,<expL2>] Pass: <expN1> - Top row screen coordinate. <expN2> - Left column screen coordinate. <expN3> - Bottom row screen coordinate. <expN4> - Right column screen coordinate. <expC1> - Prefix character(s) for memo memvar. <expC2> - Memo field database field name. <expC3> - Memo title. <expC4> - Color for memo data. <expC5> - Color for title display. <expN5> - Maximum lines memo may contain. Default unlimited. <expL1> - .F. view only, .T. allow editing. Default .T. <expL2> - .F. does nothing, .T. starts editing at the end of the memo text. Default .F. Returns: Nothing. Description: EDT_MEMO() Puts a border on the screen, a title on the top line of the border, Displays an appropriate message line, and Saves the memo data if Ctrl+W is pressed. This function may be used as a Valid function (BUILDER can create the call) or as a stand alone command. If used as a Valid function, DO NOT try to GET the memo field. Issue a GET on a one byte character memvar and EDT_MEMO() will force the user to press "Y" to edit the memo data or "N" to bypass the field. <31> The Aeolus Procedure and Function Library Reference Manual ERRTONE() Syntax: errtone([<expN>]) Pass: Nothing or one (1) through five (5). Returns: Nothing. Description: The ERRTONE() function beeps the speaker in one of five ways, a two tone error beep if no parameters (or zero) are passed, a short high pitched single tone if one (1) is passed. Passing a two (2) will make a two-tone ON indication sound, three (3) will make the opposite or a two-tone OFF sound. Passing a four (4) makes a long low error tone. <32> The Aeolus Procedure and Function Library Reference Manual ETC() Syntax: etc(<expC>,<expN1>,<expN2>,<expN3>) Pass: <expC> start time of process <expN1> start value of operation <expN2> maximum value of operation <expN3> current value, must be between <expN1> and <expN2> Returns: a character expression. Description: The ETC() function will calculate the estimated time to comple- tion of an iterative process. In order to be accurate, be sure to use this only in loops that occurs at regular intervals. Looping where some iterations are longer than others will cause some very unusual time estimates. See THERMOMETR() Sample: *************************************************************** ** ETC() function example to display current estimated time ** to compete a process. stim=time() for j=1 to 500 if time()<>stim && Should only recalculate on time change @ 1,0 say etc(stim,1,500,j) stim=time() endi inkey(.25) next <33> The Aeolus Procedure and Function Library Reference Manual FEOF() Syntax: feof([<expL>]) Pass: A Logical Expression or Nothing Returns: A logical expression Description: The FEOF() function is designed only to be used in conjunction with the FGETS() function. FEOF() Returns .T. when end of file is encountered while reading a file using the FGETS() function. Before using FEOF() you must first initialize its internal vari- ables by issuing FEOF(.F.). See the example code in the description for FGETS(). <34> The Aeolus Procedure and Function Library Reference Manual FGETS() Syntax: fgets(<expN>) Pass: A file handle of a previously FOPEN()'d or FCREATE()'d file. Returns: Next logical record in a CR/LF delimited file. Description: The FGETS() function will attempt to read the next logical record in a CR/LF delimited file. Sample: *************************************************************** ** Sample code to read the AUTOEXEC.BAT file using the ** ** Aeolus FGETS() function. ** *************************************************************** ** Open the AUTOEXEC.BAT file hndl=fopen("C:\AUTOEXEC.BAT") feof(.f.) && initialize FEOF() do whil !feof() ? fgets(hndl) && read next AUTOEXEC record endd fclose(hndl) <35> The Aeolus Procedure and Function Library Reference Manual FGETSR() Syntax: fgetsr(<expN>) Pass: A file handle of a previously FOPEN()'d or FCREATE()'d file. Returns: The previous logical record in a CR/LF delimited file. Description: The FGETSR() function will attempt to read the previous logical record in a CR/LF delimited file. Sample: *************************************************************** ** Sample code to read the AUTOEXEC.BAT file using the ** ** Aeolus FGETS and FGETSR() functions. ** *************************************************************** ** Open the AUTOEXEC.BAT file hndl=fopen("C:\AUTOEXEC.BAT") feof(.f.) && initialize FEOF() do whil !feof() ? fgets(hndl) && read next AUTOEXEC record endd ** file pointer is at the end of file, let's use FGETSR() ** to read and display AUTOEXEC.BAT backwards. feof(.f.) && reinitialize FEOF() do whil !feof() ? fgetsr(hndl) endd fclose(hndl) <36> The Aeolus Procedure and Function Library Reference Manual FIL_LOCK() Syntax: fil_lock(<expN>) Pass: <expN> seconds to wait before returning false, zero will not return false. Returns: A logical expression. Description: The FIL_LOCK() function will attempt to lock a previously opened .DBF database, if it fails in <expN> seconds an error box is displayed allowing the user to try again or abort the operation. If <expN> is passed as a value of zero then FIL_LOCK() will wait indefinitely to attempt the lock. FIL_LOCK returns true if the lock is successful and false if the lock is unsuccessful. Issuing a successful FIL_LOCK() allows a database opened in non- exclusive mode to be treated as if it were opened exclusively. Note that all other file or record locks will be rejected while you have a successful FIL_LOCK(), be sure to UNLOCK the file or close the database so others on the LAN can use it. Sample: ****************************************************** ** Attempt to lock a database previously opened in ** shared mode. ** set exclusive off && allow file sharing use addrbook if fil_lock(5) report form addr_rpt to print noeject endi unlock Comment: An alternative to using FIL_LOCK() is simply to open your data- bases in exclusive mode. Either method will accomplish the same thing. <37> The Aeolus Procedure and Function Library Reference Manual FLD_REPL() Syntax: fld_repl(<expC>,<exp>[,<expN>]) Pass: <expC> The name of the field in the currently selected database to be replaced. <exp> The value to place in the database field <expC> <expN> The number of seconds to wait for a record lock before returning false. Returns: A logical value. Description: Use FLD_REPL whenever you need to REPLACE a single database field. This function will work in a shared or single user application. Using this function on single field REPLACEs will allow your application to be changed from a single to multi-user program simply by changing the NETWORK system variable from .F. to .T.! Sample: ** replace a date field in the currently selected database ** with today's date - will work if single or multi user do fld_repl with "CURRNT_DT",date() <38> The Aeolus Procedure and Function Library Reference Manual GEN_MAINT Syntax: do gen_maint with <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ; <expC2>[,<expN5>][,<expN6>][,<expL>][,<expC3>][,<expC4>] Pass: <expN1> top left row <expN2> top left column <expN3> bottom right row <expN4> bottom right column <expC1> DBSTOR prefix character(s) <expC2> procedure name suffix <expN5> fast delete index order number <expN6> number of GET fields <expL> .T. to allow duplicates in file <expC3> menu options to use <expC4> function name to execute after file I/O and just before exit. Description: The GEN_MAINT procedure is one of two generic file maintenance procedures included with the function library and is designed to be used as an all purpose file maintenance routine. Before you can call the GEN_MAINT procedure you must first code four procedures yourself, GSAYS_????, GGETS_????, GEDIT_???? and GKEY_????. Where ???? is the value passed as <expC2>. The GSAYS_???? procedure must contain the screen displays, GGETS_???? the get's, and GEDIT_???? additional code performed after a READ statement. Call GEN_MAINT with <expN1> through <expN4> equal to the screen coordinates required. <expC1> must equal the suffix portion of the three procedures you write. <expC2> is the prefix character you want when GEN_MAINT creates memory variables. Optionally pass <expN5> as the 'fast delete' index order number. A fast delete index is created by issuing the following Clipper command: INDE ON IF(DELE(),"*"," ") TO ... If <expN5> is not passed or passed with a value of zero the database will be PACKed on every delete instead. Using the fast delete, records marked for deletion are used as 'add space' so your database doesn't grow indefinitely. Note that you must use either SET DELETED ON or SET FILTER TO !DELE() for fast delete to work correctly. <expN6> is another optional parameter that should be used if you have any VALID clauses in your file maintenance. The value passed in <expN6> should be equal to the number of fields that <39> The Aeolus Procedure and Function Library Reference Manual are in the file maintenance GET string. If you use this, exec- cute a CLEAR TYPEAHEAD in the VALID function if an error occurs. The cursor will be positioned at the error field if a VALID fails. <expL> may be passed as true if duplicate records are to be allowed. The default is false. <expC3> is used to tell GEN_MAINT which of the three basic menu options to use, Add-Change- and/or Delete. Pass a character string with the first letter of each of the menu options to allow during the GEN_MAINT. Passing "AC" for example will only put "Add", "Change" and "Find" on the file maintenance menu, skipping "Delete". Passing a null string ("") will only allow "Find". The default is "ACD" if this is parameter is not passed. <expC4> is a character string of the name of a function to be executed on every file Add, Change, or Delete and before the File Maintenance is exited. A character parameter is passed to this function indicating the action taking place "A" for Add, "C" for Change, "D" for Delete and "E" for Exit. You must return a logical value from this function. The return value is NOT checked for Adds, Changes, or Deletes. However, on Exit if the return value is false (.F.) then the user will not be allowed to exit the file maintenance. You can create your own sample calls to GEN_MAINT by creating file maintenance windows in BUILDER. Sample: proc fmnt_exmpl ** proc to call a generic maintenance routine ** m_trow=04 m_tcol=30 m_brow=12 m_bcol=67 sele TCSREPS do gen_maint with m_trow,m_tcol,m_brow,m_bcol,"REPS","Q_",.f., ; "AC","TESTFUNC" ** since the 8th parm is "AC" only Adds and Changes will be allowed ** screen SAY's for generic maint of sales rep file ** proc gsays_reps @ m_trow+2,m_tcol+2 say "Sales Rep #:" @ m_trow+4,m_tcol+2 say " Last Name:" @ m_trow+5,m_tcol+2 say " First Name:" @ m_trow+7,m_tcol+2 say " Phone:" <40> The Aeolus Procedure and Function Library Reference Manual ** screen GET's for generic maint of sales rep file ** proc ggets_REPS para g_func && A-Add, C-Change, D-Delete or null if && display only. @ m_trow+2,m_tcol+15 get &g_pfx.SLS_NBR pict "9999" clear gets @ m_trow+4,m_tcol+15 get &g_pfx.LAST pict "@!" @ m_trow+5,m_tcol+15 get &g_pfx.FIRST pict "@!" @ m_trow+7,m_tcol+15 get &g_pfx.PHONE pict "@R (999) 999-9999" ** Function to edit data called after a screen is keyed but ** before the disk write ** func gedit_REPS retu(.t.) ** key GET's for generic maint of division file ** func gkey_REPS para gk_func && A-Add, D-Del, C-Change winpush(m_brow-2,m_bcol-15,m_brow+3,m_bcol+09) message("Enter Sales Rep Number or Press ESC to Abort",24,00 ; ,80,bmsg_clr) pcd=space(4) @ m_brow-1,m_bcol-13 say "Sales Rep #:" get pcd pict "9999" @ m_brow+1,m_bcol-13 say "Enter Sales Rep # Code" if gk_func<>"A" @ m_brow+2,m_bcol-13 say "Blank for Current Rec" else @ m_brow+2,m_bcol-13 say "to Add or ESC to Exit" endi read message("",24,00,80,bmsg_clr) winpop() &g_pfx.SLS_NBR=if(empty(pcd) .or. ; lastkey()=27, ; &g_pfx.SLS_NBR,pcd) retu(pcd) func testfunc para t_func && "A"-Add, "C"-Change, "D"-Delete, "E"-Exit. do case case t_func="A" ** Record was added to database, do whatever we need to ** after that activity. case t_func="C" ** Current database record was Changed, do whatever is needed ** in that case. <41> The Aeolus Procedure and Function Library Reference Manual case t_func="D" ** Current database record is now a Deleted record, do ** whatever is needed (usually delete child relation records). case t_func="E" ** User is trying to exit the file maintenance, make sure it ** is ok for them to do so at this time. If it is then return ** true (.T.) otherwise return false (.F.) to keep them in the ** file maintenance. endc retu(.t.) <42> The Aeolus Procedure and Function Library Reference Manual GENVLD() Syntax: genvld(<expL1>,<expC1>,<expN1>,<expN2>,<expN3>,<expL2> [,<expC2>]) Pass: <expL1> - The validation test expression. <expC1> - The error message on incorrect GET input. <expN1> - The screen row number to display the error message. <expN2> - The screen column number to display the error message. <expN3> - The screen rightmost column number to pad/allow the error message to display. <expL2> - Required indicator. True (.T.) if field cannot be empty or false (.F.) if field is allowed to be empty. <expC2> - Color string for error message to display, default is WERR_CLR. Returns: A logical value. Description: The GENVLD() function is a generic valid function used to vali- date a GET for any logical expression and display an error mes- sage on invalid input. Sample: You have a two byte character GET for the U.S. state code and you would like to make sure what is keyed is legitimate code. The following GENVLD() would do this: @ dr1+05,dc1+22 get state pict "!!" valid ; genvld(in_usa(state), ; "ERROR: Not a Valid U.S. State Code",dr2-1,dc1+2,dc2-2,.t.) See the IN_USA() function in this text also. In the above sample code the user would be forced to enter a valid U.S. state code into the STATE field. Attempting to leave the field blank would produce an error beep and the error mes- sage due to the sixth parameter being set to true. Any expression that returns a logical value (including your own UDFs) may be used in place of the IN_USA() function in the example. <43> The Aeolus Procedure and Function Library Reference Manual GOT() Syntax: got(<expC>,<expN1>,<expN2>) Pass: <expC> database alias name <expN1> field number in database <expN2> record number of database Returns: an expression of type determined by TYPE(FIELD(<expN1>)). Description: Normally used in a valid function to pop up a scroll box and put the selected item in the READ field. <expC> is the database alias used for the look up, <expN1> is <expN1>th field in the database whose alias is <expC>. <expN2> is the record number in that database, usually the POP() func- tion. The return value is whatever is the databases <expN1>th field at record <expN2>. Sample: @ 12,34 say "Building # " get qbldg_nbr pict "!!!!" ; valid ckbldg() set cursor on read set cursor off ************************************************************* *** valid function to check the existence of a building ID # ** and pop a scroll box up and allow selection if the keyed ** value is not found in the building file. ** func ckbldg v=readvar() && get READ var name p=&v && get its value if empty(p) && allow a blank in this function retu(.t.) && to be a valid entry endi of=select() && old file select area or=recn() && old record (in case same file) ret_val=.t. && default return value set softseek on <44> The Aeolus Procedure and Function Library Reference Manual sele bldg seek p && look for it if !found() k_bldg=space(4) bldg_fld='bldg_nbr+" "+city' r=row() c=col() set cursor off ** display pop box at row()-1, col()+3 of the field being ** tested. ckv=got("BLDG",1,pop(r-1,c+3,6,25,"BLDG",bldg_fld,"",.t., ; .f.,"k_bldg")) set cursor on ret_val=.f. if !empty(ckv) && if a record was chosen &v=ckv && put it in the READ var keyboard chr(13) && enter key will display entry endi endi sele (of) go or retu(ret_val) <45> The Aeolus Procedure and Function Library Reference Manual HEX2DEC() Syntax: HEX2DEC(<expC>) Pass: <expC> - A string of hexadecimal digits. Returns: A numeric decimal integer of the passed hexadecimal number. Description: HEX2DEC() converts a hexadecimal character string to a numeric integer value. This function is useful when calling some of the assembly routines in the BLDRASM library. See the TIMEOUT assembly routine also. <46> The Aeolus Procedure and Function Library Reference Manual IN_CANADA() Syntax: in_canada(<expC>) Pass: <expC> - A two byte character string Returns: A logical expression. Description: The IN_CANADA() function tests the passed parameter and returns true (.T.) if the value is a valid Canadian province code (see list below), otherwise false (.F.) is returned. This function is useful when building VALID functions. See the GENVLD() sample code also. Notes: Canadian provinces tested in IN_CANADA(): AB - Alberta NF - Newfoundland BC - British Columbia NS - Nova Scotia MB - Manitoba ON - Ontario NB - New Brunswick PQ - Quebec NF - Newfoundland SK - Saskatchewan <47> The Aeolus Procedure and Function Library Reference Manual IN_USA() Syntax: in_usa(<expC>) Pass: <expC> - A two byte character string Returns: A logical expression. Description: The IN_USA() function tests the passed parameter and returns true (.T.) if the value is a valid U.S. State code (see list below), otherwise false (.F.) is returned. This function is useful when building VALID functions. See the GENVLD() sample code also. Notes: U.S. State codes tested in IN_USA(): AL - Alabama KY - Kentucky ND - North Dakota AK - Alaska LA - Louisiana OH - Ohio AZ - Arizona ME - Maine OK - Oklahoma AR - Arkansas MD - Maryland OR - Oregon CA - California MA - Massachusetts PA - Pennsylva- nia CO - Colorado MI - Michigan RI - Rhode Island CT - Connecticut MN - Minnesota SC - South Caro- lina DE - Delaware MS - Mississippi SD - South Dakota DC - Washington D.C. MO - Missouri TN - Tennessee FL - Florida MT - Montana TX - Texas GA - Georgia NE - Nebraska UT - Utah HI - Hawaii NV - Nevada VT - Vermont ID - Idaho NH - New Hampshire VA - Virginia IL - Illinois NJ - New Jersey WA - Washington IN - Indiana NM - New Mexico WV - West Virgi- nia IA - Iowa NY - New York WI - Wisconsin KS - Kansas NC - North Carolina WY - Wyoming Note: The codes for Puerto Rico (PR) and the U.S. Virgin Islands (VI) are not tested. <48> The Aeolus Procedure and Function Library Reference Manual INFILE() Syntax: infile(<expC1>,<expN1>,<expC2>,<expN2>,<expN3>,<expN4>, ; <expL>[,<expC3>]) Pass: <expC1> - File alias name of look up table. <expN1> - Index order number for SEEK. <expC2> - The error message on incorrect GET input. <expN2> - The screen row number to display the error message. <expN3> - The screen column number to display the error message. <expN4> - The screen rightmost column number to pad/allow the error message to display. <expL> - Required indicator. True (.T.) if field cannot be empty or false (.F.) if field is allowed to be empty. <expC3> - Color string for error message to display, default is WERR_CLR. Returns: A logical value. Description: The INFILE() function tests the input of the @...GET and dis- plays an error message if the value entered is not FOUND() in a database. The programmer may allow or disallow the entry of a blank into the field with <expL> Sample: You have a four byte character GET for an employee number and you would like to make sure what is keyed is a legitimate code. Further there is an employee file with index order one (1) on the four digit employee code. The following get will force the entry of a valid employee code based on the look up table (called EMPLYEE). @ dr1+05,dc1+22 get emp_nbr pict "!!" valid ; infile("EMPLYEE",1, ; "ERROR: Not a Valid Employee Code",dr2-1,dc1+2,dc2-2,.t.) In the above sample code the user would be forced to enter a valid employee code into the EMP_NBR field. Attempting to leave the field blank would produce an error beep and the error mes- sage due to the seventh parameter being set to true. The INFILE() function is only useful if you specifically do not want to help your users find the required field entry from the look up table. Sometimes this is necessary, however, I believe the PCKVLD() function will be useful in more situations. <49> The Aeolus Procedure and Function Library Reference Manual INPATH() Syntax: inpath(<expC1>[,<expC2>]) Pass: <expC1> - DOS filename to locate. <expC2> - environment variable with pathnames separated by semicolons of paths to search for <expC1>. Default value is "PATH". Returns: A character value of the path where <expC1> is located. A null string is returned if it was not found. A "." (period charac- ter) is returned if it was found in the current directory. Description: The INPATH() function first searches the current DOS directory for the file <expC1> and returns "." if it is found. It then searches each directory in the DOS PATH environment variable or if <expC2> is passed that environment variable. If <expC2> is passed it must contain directory names separated by semicolons just like the DOS PATH. <50> The Aeolus Procedure and Function Library Reference Manual ISEEK() Syntax: iseek(<exp>[,<expC>][,<expN>][,<expL>]) Pass: <exp> expression to SEEK <expC> database alias name, default is current select alias. <expN> index order number to use for SEEK command, default used is the current index order. <expL> .T. to use SOFTSEEK ON, .F. for SOFTSEEK OFF, default is the current SOFTSEEK setting. Returns: a logical expression. Description: The ISEEK() function does an indexed search of a database and returns the FOUND() condition. <exp> is the key value to search for, <expC> is the database alias to SELECT for the indexed search. <expN> is the index order number to use in the search, if zero or not supplied the current index order is used. <expL> to true to use 'softseek on' or false for 'soft-seek off', if <expL> is not passed the current SOFTSEEK setting is used. Sample: ****************************************************** ** ISEEK() function example ** select 0 use customer index on cust_nbr to cstmr1 index on trim(lname)+" "+fname to cstmr2 set index to cstmr1,cstmr2 clea mcust_nbr=space(9) @ 1,1 say "Enter Customer Number" get mcust_nbr read if iseek(mcust_nbr,"CUSTOMER",1,.f.) @ 2,1 say "Customer Number Found." endi <51> The Aeolus Procedure and Function Library Reference Manual LSIDE The LSIDE procedure is called by the TOTALKEYON and TOTALKEYOFF procedures only and should not be used otherwise. Please see the TOTALKEYON and TOTALKEYOFF procedures for additional infor- mation. This is included only for completeness. <52> The Aeolus Procedure and Function Library Reference Manual MAKE_EMPTY() Syntax: make_empty(<expC>) Pass: <expC> existing memory variable name Returns: an expression of TYPE(<expC>). Description: The memory variable name <expC> is returned in its empty form. A character variable is spaces the length of the passed variable, a numeric is returned as zero, etc. Sample: ****************************************************** *** Make empty function example *** tst_dat=date() ? make_empty("TST_DAT") && same as ctod(" / / ") tst_nbr=998 ? make_empty("TST_NBR") && same as 0 (zero) tst_chr="Software Can be Groovy" ? make_empty("TST_CHR") && same as space(22) <53> The Aeolus Procedure and Function Library Reference Manual MAKDIR Syntax: call makdir with <expC> Pass: <expC> - Name of new DOS subdirectory to create. Returns: Nothing. Description: The MAKDIR assembly subroutine attempts to create the DOS subdi- rectory passed as <expC>. No error checking is done and there is no return value. This routine is useful when writing installation programs or end of year archiving and any other reason you may have to create a DOS subdirectory from your Clipper program. You can test the results of MAKDIR using CHGDIR, CHGDSK and CURDIR() See CHGDIR, CHGDSK <54> The Aeolus Procedure and Function Library Reference Manual MAXHNDLS() Syntax: maxhndls([<expN>) Pass: Zero/nothing or a numeric expression Returns: If zero or nothing is passed MAXHNDLS() returns the number of file handles available to the program If a number is passed, MAXHNDLS returns true if the number of file handles available is equal or greater, otherwise MAXHNDLS() returns false. If false is to be returned MAXHNDLS() will dis- play an error box before returning. Description: Allows a Clipper program to determine the number of available file handles in the current system configuration. Also displays errors if fewer than <expN> file handles are pre- sent in the current configuration. <55> The Aeolus Procedure and Function Library Reference Manual MEM_HELP Syntax: do mem_help Pass: Nothing. Returns: Nothing Description: The MEM_HELP procedure is the three pages of help available when entering a memo field through the EDT_MEMO() function. There should never be a need for BUILDER users to call it and is included here only for completeness. See EDT_MEMO(), SHOW_MEMO <56> The Aeolus Procedure and Function Library Reference Manual MEMFUNC() Syntax: memfunc(<expN1>,<expN2>,<expN3>) Pass: <expN1> - MEMOEDIT() mode <expN2> - MEMOEDIT() row <expN3> - MEMOEDIT() column Returns: A numeric expression for MEMOEDIT() to interpret. Description: The MEMFUNC() function is called on every keypress while editing a memo field called from the SHOW_MEMO procedure. It's only function is to limit the number of lines a user can enter into a memo field (if that parameter was passed). It should not be called and is included only for completeness. See EDT_MEMO(), SHOW_MEMO <57> The Aeolus Procedure and Function Library Reference Manual MESSAGE() Syntax: message(<expC1>,<expN1>,<expN2>[,<expN3>][,<expC2>]) Pass: <expC1> text to display on the screen <expN1> row to display <expN2> column to display <expN3> length to pad/truncate message text <expC2> alternate color choice Returns: Nothing. Description: The MESSAGE() function places <expC1> on the screen at row <expN1> column <expN2> and pads <expC1> (or trims it) to a length of <expN3>. <expC2> may be used as an alternate color choice. If <expN3> is not used, the LEN(<expC1>) is used instead. If <expC2> is not passed, the current color is used. Sample: *********************************************************** *** MESSAGE function example. *** message("Test Message 1",01,00,80,"+w/b") inkey(0) <58> The Aeolus Procedure and Function Library Reference Manual MSGBOX() Syntax: msgbox(<expC1>[,<expC2>][,<expC3>][,<expC4>][,<expN1>] [,<expN2>][,<expN3>][,<expN4>]) Pass: <expC1> message for line one or array name. <expC2> alternate color choice <expC3> message for line two - input prompt <expC4> character list for allowable input (null ("") for any key) <expN1> top left row <expN2> top left column <expN3> bottom right row <expN4> bottom right column Returns: nothing or a character expression depending on the value of <expC4>. Description: This function puts a message box on the screen and waits for an acknowledgment. If only <expC1> is passed as an argument a box is centered on the screen sized to fit <expC1> inside. The message is dis- played in bright yellow with a red background by default, useful for error messages. Pass <expC2> as an alternate color choice. <expC3> and <expC4> usually work together, <expC3> is a prompt and <expC4> is a list of characters that, when entered from the keyboard, will remove the box from the screen. <expC4> need only contain one of each alphabetic character as it is converted to upper case before being used by MSGBOX(). <expN1> and <expN2> are optional row and column screen positions for the box. <expN3> and <expN4> may be passed to optionally size the box. <59> The Aeolus Procedure and Function Library Reference Manual Sample: ********************************************************* *** MSGBOX function example *** msgbox("Error Message") msgbox("Information Message","+w/b") if msgbox("Do You Play the Piano?","+w/b","Press Y or N", ; "YN",10,5)="Y" msgbox("You Pressed Yes","+w/b") else msgbox("You Pressed No","+w/b") endi ** ONLY FOR ARRAYs: Each element may (optionally) be prefixed ** with "@L" to left justify, "@R" to right justify or "@C" to ** center that element inside the box. If not used the default ** is "@L". decl msg[0x] msg[01]="An ARRAY message" msg[03]="for the MSGBOX() function to" msg[05]="to Display!" msg[07]="@CI'm Centered !" msg[08]="@RRight Justified." msgbox(@msg) <60> The Aeolus Procedure and Function Library Reference Manual NET_USE() Syntax: net_use(<expC1>,<expL>,<expN>,<expC2>) Pass: <expC1> database alias name <expL> .T. for exclusive open, .F. for shared <expN> error timeout seconds if cannot be opened <expC2> alias to use when file is opened Returns: a logical expression. Description: Opens the database <expC1> in exclusive mode if <expL> is true or non-exclusive if <expL> is false. If <expN> is the seconds before an error timeout. <expC2> is the alias that will be used. Comment: It is suggested that you use the OPEN_FIL procedure instead of the NET_USE() function, as it automatically handles error condi- tions and parameter passing is more convenient. <61> The Aeolus Procedure and Function Library Reference Manual NOT_REQ() Syntax: not_req(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>]) Pass: <expC1> - Error message if field is not blank. <expN1> - Screen row coordinate to display error message. <expN2> - Screen column coordinate to display error message. <expN3> - Rightmost screen column to display error message. <expC2> - Color to display error message. Default is WERR_CLR. Returns: A logical value. Description: There are times when you may want to force a user to enter an @...GET as a blank. The NOT_REQ() valid function is used in these (rare) cases. Usually conditionally executed. Sample: In the following sample @...GETs the user is required to enter a state code and a country name. If the state code is a valid U.S. state then the country name must be blank otherwise the country name field is required. Program this using BUILDER valids as follows: ** Force a valid U.S. State or Canadian Province or blank ** @ dr1+07,dc1+17 get state pict "!!" valid ; genvld(in_usa(state) .or. in_canada(state), ; "ERROR: Not a Valid State or Province",dr2-1,dc1+2,dc2-2,.f.) ** if the state code is valid U.S. state then the country name ** must be blank, otherwise the country name is required. @ dr1+08,dc1+17 get country valid ; if(in_usa(state), ; not_req("Leave Country Blank",dr2-1,dc1+2,dc2-2), ; req("Country Name is Required",dr2-1,dc1+2,dc2-2)) <62> The Aeolus Procedure and Function Library Reference Manual NUMERIC() Syntax: numeric(<expC>) Pass: <expC> a string that may or may not contain all numerics Returns: a logical expression. Description: This function scans every character in <expC> and if every character is between '0' and '9' then it returns true, otherwise false is returned. <63> The Aeolus Procedure and Function Library Reference Manual OPEN_FIL() Syntax: open_fil(<expC1>[,<expL1>][,<expC2>][,<expL2>]) Returns: a logical expression. Pass: <expC1> database name to open <expL1> .T. for shared open, nothing or .F. for exclusive open <expC2> alias name when open, if other than database name <expL2> .T. to exit to DOS on open errors, .F. to return false on open errors. Description: The OPEN_FIL function will attempt to open the file <expC1> in exclusive mode-even if SET EXCLUSIVE OFF is in effect-unless the second parameter is sent as true. Use the third parameter to set the alias if you want the alias other than the default of <expC1>. <expL2> determines how the OPEN_FIL function will react when it cannot open a .DBF file, passing .T. (or not pass- ing this parameter) will cause OPEN_FIL to exit to DOS on error conditions. Passing <expL2> as .F. will cause OPEN_FIL to return a logical false if it fails to open the file. The OPEN_FIL function tests for four (4) error conditions. If an error is detected, an error box is displayed and OPEN_FIL either exits to DOS or returns false to the application depend- ing on the value of <expL2>. The errors tested for are as fol- lows: 1. Invalid Alias Name. If no specific alias name is sent to the OPEN_FIL function the file name (<expC1>) is used. A valid alias name must contain the letter 'A' through 'Z' in the first character position. The second through tenth character posi- tions can contain 'A' through 'Z', '0' through '9' or '_'. 2. File not found. Before a database is USEd OPEN_FIL tests the Clipper FILE() function to determine if the file exists. 3. Already in Use. The database is already USEd in EXCLUSIVE mode or the file has been locked. 4. .DBT file is missing. OPEN_FIL tried to USE a database but the memo field data file (.DBT file) is missing. <64> The Aeolus Procedure and Function Library Reference Manual PADC() Syntax: padc(<expC1>,<expN>[,<expC2]) Pass: <expC1> text to pad/truncate <expN> length of returned string <expC2> fill character, default is space Returns: a character expression. Description: This function pads or trims <expC1> to a length of <expN> using <expC2> as the fill character. PADC() returns a centered char- acter string. <65> The Aeolus Procedure and Function Library Reference Manual PADL() Syntax: padl(<expC1>,<expN>[,<expC2]) Pass: <expC1> text to pad/truncate <expN> length of returned string <expC2> fill character, default is space Returns: a character expression. Description: This function pads or trims <expC1> to a length of <expN> using <expC2> as the fill character. PADL() returns a right justified character string. <66> The Aeolus Procedure and Function Library Reference Manual PADR() Syntax: padr(<expC1>,<expN>[,<expC2]) Pass: <expC1> text to pad/truncate <expN> length of returned string <expC2> fill character, default is space Returns: a character expression. Description: This function pads or trims <expC1> to a length of <expN> using <expC2> as the fill character. PADR() returns a left justified character string. <67> The Aeolus Procedure and Function Library Reference Manual PCKVLD() Syntax: pckvld(<expC1>,<expN1>,<expN2>,<expL1>,<expC2>,<expL2> ; [,<expC3>][,<expC4>]) Pass: <expC1> - File alias name for picklist. <expN1> - Field ordinal number in database to place in GET field on pick list selection. <expN2> - Index order number to use on <expC1> to find the GET input data. <expL1> - .T. = Use QWERTY scroll. .F. Do not use QWERTY scroll. <expC2> - Display expression for picklist. <expL2> - .T. = accept blank for GET input, .F. = force entry into GET. <expC3> - Key value SEEK prefix. Default nothing. <expC4> - STAY AT field name for a bounded by picklist. Default is no bounded by field. Returns: A logical expression. Description: The PCKVLD() function can only be used in the VALID of a GET. PCKVLD() will SEEK on the <expC1> database using index order <expN2> and if value of FIELD(<expN1>) is equal to the value entered into the GET the cursor will move to the next field in the GET stream. If there is not an exact match a pick list is given to the user with the highlight bar positioned to the near- est record to the GET input. The user may then move to the desired record, and press ENTER to put that data into the GET field an move to the next field in the GET stream. See POP(). Sample: You are building an order entry system and one of the fields on the order is 'Sales Person'. This field is a three character field of the persons initials. You want to verify that what is entered into this field is a valid employee, but also that the employee is a sales person. PCKVLD() can be used to do this in the following manner. Technical assumptions: Employee file is called "EMPLYEE". The field EMPLYEE->TYPE is a one byte character field indicating the department the employee works in. That EMPLYEE->TYPE="S" is the sales department. <68> The Aeolus Procedure and Function Library Reference Manual The field EMPLYEE->INITIALS is a three byte character field of the employees initials. Index order number one has the index key TYPE+INITIALS on the EMPLYEE file. The field EMPLYEE->INITIALS is the second field in the database. ** The following PCKVLD() will not allow QINV_SLSMAN ** to be blank. Will only allow entry if these Clipper ** program statements ... ** ** SELECT EMPLYEE ** SET ORDER TO 1 ** SEEK "S"+QINV_SLSMAN ** ** ... set FOUND() to .T. ** ** If the entry is not FOUND() then a pick list is presented ** displaying the initials, first, and last name. The picklist ** will only display EMPLYEE->TYPE="S" records because of the ** index key expression, the key prefix passed, and the bounded ** by being set. ** @ dr1+11,dc1+23 get qinv_slsman pict "!!!" valid ; pckvld("EMPLYEE",2,1,.f., ; 'initials+" "+fname+" "+lname',.t.,"S","TYPE") The PCKVLD() function is easier to digest if you understand the POP() function. The source code to call this function can be automatically generated by BUILDER. <69> The Aeolus Procedure and Function Library Reference Manual PLIST() Syntax: plist(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expN5>,<expC2> ; [,<expL1>][,<expC3>][,<expC4>][,<expC5>][,<expC6>] ; [,<expL2>][,<expL3>][,<expC7>] Pass: <expN1> top row for picklist box <expN2> left column for picklist box <expN3> bottom row for picklist box <expN4> right column for picklist box <expC1> database alias name <expN5> index order number used for picklist <expC2> expression to display on each picklist line <expL1> enable QWERTY scroll function, default false. <expC3> memvar for QWERTY scroll initialization (prefix with @) <expC4> color for pointer bar, if not using WREV_CLR <expC5> procedure to execute on ENTER key <expC6> condition expression for bounded picklist <expL2> PLIST() to display message line? <expL3> PLIST() to display border? <expC7> Seek prefix when QWERTY scroll is used. Returns: a numeric expression. The record number selected. Description: The PLIST() function creates a scrollable pick list box to be pre- sented on the screen. This function is a replacement for the POP() function of BUILDER ver 1.0. POP() is kept in the librar- y for compatibility. <expN1> and <expN2> are the row and column of the upper left corner of the pick list box. <expN3> and <expN4> are the height and width of the box respec- tively <expC1> is the database alias to 'browse'. <expN5> is the index order number to use when this picklist if being viewed. When <expC2> is evaluated as a macro it is displayed on each line in the box. If <expL1> is passed as true then a field delimited with square brackets will be placed on the top of the box. Any QWERTY text entered will be displayed between the brackets and that text will be used as a SEEK key and the POP() box will be refilled using that value. If <expC7> was passed the SEEK value will be <70> The Aeolus Procedure and Function Library Reference Manual <expC7> + QWERTY value before refilling the PLIST() box. <expC3> is used in conjunction with <expL1> and contains the name of the memory variable that contains the starting key value to be placed between the square brackets. If you choose to set <expL1> to true and not use this argument the QWERTY area will be sized according to the length of the INDEXKEY(0) function. <expC4> is an optional color for the pointer bar. <expC5> is an optional (strongly recommended) name of a proce- dure to be executed on selection of an element. Warning: <expC5> can only contain the procedure name and cannot contain a 'WITH' clause or parameters. <expC6> is an optional logical expression that will restrict scrolling only while the expression returns true (.T.). This expression must return true (.T.) when PLIST() is initially called. Pass this parameter as a character expression that when evaluated as a macro will return a logical value. Warning: if you use <expC6> to set database bounds AND <expL1> is set to true, you will need to also use <expC7> (SEEK pre- fix). Use <expL2> and <expL3> to optionally turn off some PLIST() default display items. Both <expL2> and <expL3> default to true (.T.). Pass false (.F.) in <expL2> and PLIST() will not display it's default message line. Pass false (.F.) in <expL3> and PLIST() will not display a window border around the PLIST() data. Sample: ***************************************************** * This example displays a pick list box at row 2 * column 40, it is 9 rows tall and 23 columns wide. * It displays the field COUNTRY from the database * INTRNTNL and provides the user a field to enter QWERTY * text to move to different parts of the database. * If a record is selected the procedure INTL_DTL is executed. sele intrntnl go top ** display international ** sele intrntnl kf=space(20) intl_rec=pop(02,40,9,23,"INTRNTNL",1,"country",.t., ; @KF,"","intl_dtl") <71> The Aeolus Procedure and Function Library Reference Manual Sample2: ***************************************************** * This example displays a pick list box at row 2 * column 19, it is 9 rows tall and 20 columns wide. * It displays the fields PART_NBR and PART_END from the * database MSPART. * If a record is selected the procedure MS_DETAIL is executed. sele mspart go top ** display part list ** ms_fld='part_nbr+"-"+part_end' prt_rec=plist(02,19,11,39,"MSPART",1,ms_fld,.t.,"","", ; "ms_detail") Sample 3: ************************************************************* ** This example will display a picklist box on the screen and ** combine both the Bounded by AND the QWERTY scroll features ** The last parameter passed allows this, however, careful ** consideration must also be given to the index and database ** being used. ** ** We will browse the database PARTS which is a very large ** database with part numbers and names we want to display. ** This database also has a code to indicate what type of ** part the record contains. There are three part type codes ** "P"-Plumbing, "H"-Heating, and "E"-Electrical. ** ** Before reaching this point in the program the user has ** already selected the part type to be viewed. So the ** picklist should be bounded by the PART_TYP field. ** The only part type to be displayed in this pick list is ** indicated in the memvar DTYP which is equal to "P", "H", ** or "E" before this area of the program is executed ** ** Since there are so many parts of each type, we will also ** provide a QWERTY scroll field to allow faster locating. ** ** Index order one has the index key expression of: ** PART_TYP+PART_NBR ** ** PART_TYP is Character 1 byte long ** PART_NBR is Character 12 bytes long ** ** If a part number is selected, proceed to the order entry ** screen, procedure ORD_ENTRY <72> The Aeolus Procedure and Function Library Reference Manual bpart_typ=PARTS->part_typ bcond="PART_TYP==BPART_TYP" kf=space(12) && length of part number for qwerty && scroll default would be length of && index expression, in this case 13. ** set up the display expression de='transform(part_nbr,"@R 99-999999-999-!")+" "+desc' ** display the picklist plist(02,01,14,66,"PARTS",1,DE,.t.,@kf,"","ORD_ENTRY", ; BCOND,.t.,.t.,DTYP) ** Parms 1-4 set the screen coordinates. ** Parms 5 and 6 are the database alias name and index order ** used during picklist operation. ** Parm 7 (DE) is the display expression defined above. ** Parm 8 (.T.) turns on the QWERTY scroll feature. ** Parm 9 (@kf) passes the QWERTY scroll initialization ** value. This could also have been initialized like: ** kf=PARTS->part_nbr ** to put something IN the picklist entry field. ** Parm 10 ("") nothing, use the default color for the ** highlight bar. ** Parm 11 ("ORD_ENTRY") the procedure named ORD_ENTRY ** will get executed after the ENTER key is pressed. i.e. ** a part is selected. ** Parm 12 (BCOND) passes the Bounds condition variable. ** This memvar is set above and if macro'd returns true, ** all records where this returns false will not be visible ** in this picklist. ** Parms 13 and 14 tell PLIST() to display a window border and ** a default message line ** Parm 15 (DTYP) Required for Bounded QWERTY picklists. When ** a QWERTY key is pressed, the SEEK will be on DTYP+{Current- ** QWERTY-Text}. <73> The Aeolus Procedure and Function Library Reference Manual POP() Syntax: pop(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>,<expC2> ; [,<expL1>][,<expC3>][,<expC4>][,<expC5>][,<expC6>] ; [,<expL2>][,<expL3>][,<expC7>] Pass: <expN1> top left row for picklist box <expN2> top left column for picklist box <expN3> picklist height in rows <expN4> picklist width in columns <expC1> database alias name <expC2> expression to display on each picklist line <expL1> enable QWERTY scroll function, default false. <expC3> memvar for QWERTY scroll initialization (prefix with @) <expC4> color for pointer bar, if not using WREV_CLR <expC5> procedure to execute on ENTER key <expC6> database fieldname for bounded picklist <expL2> POP() to display message line. <expL3> POP() to display border. <expC7> Seek prefix when QWERTY scroll is used. Returns: a numeric expression. The record number selected. Description: The POP() function creates a scrollable pick list box to be pre- sented on the screen. <expN1> and <expN2> are the row and column of the upper left corner of the pick list box. <expN3> and <expN4> are the height and width of the box respec- tively <expC1> is the database alias to 'browse'. When <expC2> is evaluated as a macro it is displayed on each line in the box. If <expL1> is passed as true then a field delimited with square brackets will be placed on the top of the box. Any QWERTY text entered will be displayed between the brackets and that text will be used as a SEEK key and the POP() box will be refilled using that value. If <expC7> was passed the SEEK value will be <expC7> + QWERTY value before refilling the POP() box. <expC3> is used in conjunction with <expL1> and contains the name of the memory variable that contains the starting key value to be placed between the square brackets. If you choose to set <expL1> to true and not use this argument the QWERTY area will <74> The Aeolus Procedure and Function Library Reference Manual be sized according to the length of the INDEXKEY(0) function. <expC4> is an optional color for the pointer bar. <expC5> is an optional (strongly recommended) name of a proce- dure to be executed on selection of an element. Warning: <expC5> can only contain the procedure name and cannot contain a 'WITH' clause or parameters. <expC6> is an optional fieldname that will restrict scrolling only while the fieldname passed is equal to the value on entry into the POP() function. The database must be sorted or indexed so that the passed fieldname will have the same value for a con- tiguous series of records. Warning: <expC6> can only be use if <expL1> is set to false. Use <expL2> and <expL3> to optionally turn off some POP() default display items. Both <expL2> and <expL3> default to true (.T.). Pass false (.F.) in <expL2> and POP() will not display it's default message line. Pass false (.F.) in <expL3> and POP() will not display a window border around the POP() data. Sample: ***************************************************** * This example displays a pick list box at row 2 * column 40, it is 9 rows tall and 23 columns wide. * It displays the field COUNTRY from the database * INTRNTNL and provides the user a field to enter QWERTY * text to move to different parts of the database. * If a record is selected the procedure INTL_DTL is executed. sele intrntnl go top ** display international ** sele intrntnl kf=space(20) intl_rec=pop(02,40,9,23,"INTRNTNL","country",.t., ; @KF,"","intl_dtl") Sample2: ***************************************************** * This example displays a pick list box at row 2 * column 19, it is 9 rows tall and 20 columns wide. * It displays the fields PART_NBR and PART_END from the * database MSPART. * If a record is selected the procedure MS_DETAIL is executed. <75> The Aeolus Procedure and Function Library Reference Manual k_part_nbr=space(8) sele mspart go top ** display part list ** sele mspart kf="K_PART_NBR" ms_fld='if(empty(part_nbr),space(17),part_nbr+"-"+part_end)' prt_rec=pop(02,19,9,20,"MSPART",ms_fld,.t.,"","", ; "ms_detail") <76> The Aeolus Procedure and Function Library Reference Manual POP_KEY The POP_KEY procedure is called by the POP() function only and should not be used otherwise. Please see the POP() function for additional information. This is included only for completeness. <77> The Aeolus Procedure and Function Library Reference Manual PUBL_COLO Syntax: do publ_colo Pass: Nothing Description: The BUILDER executes this procedure in the initialization of all the programs it creates. This procedure creates several public variables and initializes them for use by the program. The initialized variables are: HDR_CLR screen header box color HDR_MSG header message color BKGD_CLR screen background color BMSG_CLR background message color BERR_CLR background error color BREV_CLR background reverse color WNDW_CLR window color WMSG_CLR window message color WERR_CLR window error color WREV_CLR window reverse color WNDW2_CLR secondary window color WMSG2_CLR secondary window message color SHDW_CLR shadow color ERR_CLR error box color MSG_CLR message line color Most of these are modifiable using the "Colors" option of the BUILDER main menu. <78> The Aeolus Procedure and Function Library Reference Manual REC_LOCK() Syntax: rec_lock(<expN>) Pass: <expN> seconds before error timeout, pass zero to never timeout. Returns: A logical expression. Description: Attempts to lock the record of the currently selected data- base for timeout period of <expN> seconds. If the record cannot be locked after the timeout period an error box is presented to try again, if No is selected, a logical false is returned. If <expN> is zero or not passed to the function, REC_LOCK() will wait indefinitely. Comment: The SAVE_IT() function performs all record locking before any file I/O and you should not have to use this function. However... some shops require that a record is locked during editing and all the functions and procedures here only lock a record immedi- ately before any file I/O so you may need to use this function. <79> The Aeolus Procedure and Function Library Reference Manual REL_MAINT Syntax: REL_MAINT(<expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ; <expC2>,<expC3>,<expC4>,<expN5>,<expN6>[,<expC5>][,<expC6>] Pass: <expN1> The row number to put the Add/Change/Delete menu, usu- ally the top border of the window. <expN2> The column number for the Add/Change/Delete menu, yes, you calculate to center it. <expN3> The row number for messages, usually the bottom line of the box, not the border but inside the box. <expN4> The column number for messages, usually two spaces to the right of the left window border. <expC1> You must declare a procedure that contains the GETs for the maintenance the first three letters of which must be 'GET'. Pass in <expC1> the characters you add to make the procedure unique. <expC2> The condition that relates the file to be edited, this must be a logical true when evaluated as a macro. All contiguous records where the condition remains true will be available for editing. Note: The SET RELATION TO ... command does NOT need to be in effect to use this procedure, the databases merely need to have a one to many relationship. <expC3> Database alias name to be edited. <expC4> Memory variable prefix character(s). <expN5> The 'delete index' order number, zero (0) if a 'delete index' is not used. <expN6> The number of fields to be edited. <expC5> The first character of each menu pad to use. <expC6> User function executed on file I/O and before exit. <expC5> and <expC6> work identically to the last two parameters passed to GEN_MAINT. See the documentation on that procedure for more information on these parameters. Description: The REL_MAINT procedure is used to edit the 'many' records in the child database when a one-to-many database relationship exists. This function is designed to be easily created from a BUILDER dialog box. If you are unsure what a 'delete index' is refer to the GEN_MAINT procedure for clarification. Look carefully at the following sample to see how to set up a REL_MAINT call. <80> The Aeolus Procedure and Function Library Reference Manual Sample: ** note: prior to calling rel_maint all fields in the database ** have been copied to memory variables with identical names ** except the memory variables (in this example) are prefixed ** with the letter "Q". See DBPUBL, DBSTOR for more info. ************************************************ ** CALLED BY: Pick List Window Proc: PLST003 ** ** Comment: Model Maint Dialog ** ************************************************ proc dlog004 private dr1,dc1,dr2,dc2 ** save key to a memory variable ** important you code something like this! rpartno=model->partno dr1=15 dc1=45 dr2=dr1+04 dc2=dc1+32 set colo to (wndw_clr) winpush(dr1,dc1,dr2,dc2) @ dr1+02,dc1+04 say "Model Number" ** call rel_maint to edit all contiguous records in the MODEL ** database with the field MODEL->PARTNO equal to the memory ** variable RPARTNO. rel_maint(; dr1,dc1+6,dr2-1,dc1+2,"004","MODEL->PARTNO=RPARTNO", ; "MODEL","Q",2,1) winpop() ** this proc created by copying the GETs created by BUILDER to ** a proc with the first three characters equal to "GET", I ** arbitrarily chose "004" as the second part of the name ( ** because it matches DLOG004) and pass "004" as the fifth ** parameter above. proc get004 para g_func && A-Add, C-Change, D-Delete. ** absolutely IMPERATIVE the key variables get set from ** previously saved memory variables here!! qpartno=rpartno @ dr1+02,dc1+18 get qmodel pict "@!" Not including the comments only four lines of code were added to a BUILDER dialog box to create this (many more were deleted). <81> The Aeolus Procedure and Function Library Reference Manual This is a small example, but should clearly show how to set up a REL_MAINT of your own. <82> The Aeolus Procedure and Function Library Reference Manual REQ() Syntax: req(<expC1>,<expN1>,<expN2>,<expN3>[,<expC2>]) Pass: <expC1> - Error message if field is blank. <expN1> - Screen row coordinate to display error message. <expN2> - Screen column coordinate to display error message. <expN3> - Rightmost screen column to display error message. <expC2> - Color to display error message. Default is WERR_CLR. Returns: A logical value. Description: This VALID function forces entry of an @...GET field to be non- blank. It simply checks if the GET value is EMPTY() and only allows the cursor past the GET is it is not EMPTY(). Sample: In this example the system you are building has a date field on a screen and the field must be entered, it cannot be blank. That is all the validation that can be performed. The following REQ() function will accomplish this. @ dr1+05,dc1+11 get mdate valid ; req("A Date is Required",dr2-1,dc1+2,dc2-2) <83> The Aeolus Procedure and Function Library Reference Manual RGHT_JST() Syntax: rght_jst([<expC>]) Returns: A logical true (.T.) Pass: <expC> - Fill character after field is right justified. Default space. Description: The RGHT_JST() VALID function will right justify and fill a character field with <expC> or spaces if <expC> is not passed. Sample: Suppose you have a field to be keyed by a user and for whatever reason it makes sense to make it a character field. You also want to right justify and zero fill the field because the field will be used as the key value to look up something in another database. Use the RGHT_JST() function to accomplish this in the following manner: mkeyval=space(07) @ dr1+01,dc1+14 get mkeyval pict "9999999" valid ; rght_jst("0") If the user keys one (1) and then presses ENTER then MKEYVAL will equal "0000001". If twenty-one (21) is entered then MKEYVAL will equal "0000021" The field will be right justified. <84> The Aeolus Procedure and Function Library Reference Manual RSIDE The RSIDE procedure is called by the TOTALKEYON and TOTALKEYOFF procedures only and should not be used otherwise. Please see the TOTALKEYON and TOTALKEYOFF procedures for additional infor- mation. This is only included for completeness. <85> The Aeolus Procedure and Function Library Reference Manual SAVE_IT() Syntax: save_it(<expC1>,<expC2>,<expN>,<expC3>) Pass: <expC1> "ADD", "CHG" or "DEL" only <expC2> memory variable prefix character(s) <expN> fast delete index order number <expC3> database alias name Returns: a logical expression. Description: The SAVE_IT() function will add, change or delete the current record from the database <expC3>. The SAVE_IT() function uses file locking if the memory variable NETWORK is set to true. The <expC1> argument must be equal to "ADD", "CHG" or "DEL" to tell SAVE_IT() to add, change or delete a record. <expC2> is the character or characters the field variables are prefixed with to create the memory variables (See the DBPUBL and DBSTOR proce- dures). Use <expN> to pass the order number of the "fast delete" index order number created like: INDEX ON IF(DELE(),"*"," ") TO ... Send <expN> as zero (0) if you are not using a "fast delete". If the NETWORK memory variable is set to true and the SAVE_IT() function cannot lock the requested record and the user replies "No" to try the lock again, then the SAVE_IT() function will return false. Sample: ************************************************************* *** SAVE_IT() function example *** select 0 use customer inde cust1,cust2 do dbpubl with "Q" && setup memvars do dbstor with "Q","EMPTY" && set original values ** cust1 indexed on cust_nbr ** cust2 indexed on if(dele(),"*"," ") . . change memvars to values for new record . if !save_it("ADD","Q",2,"CUSTOMER") <86> The Aeolus Procedure and Function Library Reference Manual msgbox("ERROR--RECORD NOT ADDED !") return endi <87> The Aeolus Procedure and Function Library Reference Manual SETMSGLIN() Syntax: setmsglin([<expC>]) Description: The SETMSGLIN() function returns the screen text on line 24. If <expC> is passed then <expC> is displayed on line 24 using the value of MSG_CLR as the color value. <88> The Aeolus Procedure and Function Library Reference Manual SHADOW() Syntax: shadow(<expN1>,<expN2>,<expN3>,<expN4>) Pass: <expN1> top left row <expN2> top left column <expN3> bottom right row <expN4> bottom right column Description: Places a shadow on the area bounded by the four passed coordi- nates, where <expN1> and <expN2> are the upper left row and col- umn coordinates and <expN3> and <expN4> are the lower right. Comment: the WINPUSH procedure uses this function to place a shadow on the window it creates. You therefore should not have to use this function. <89> The Aeolus Procedure and Function Library Reference Manual SHOW_MEMO Syntax: do show_memo with <expN1>,<expN2>,<expN3>,<expN4>,<expC1>, ; <expL1>[,<expC2>][,<expN5>][,<expL2>] Pass: <expN1> - Top row screen coordinate. <expN2> - Left column screen coordinate. <expN3> - Bottom row screen coordinate. <expN4> - Right column screen coordinate. <expC1> - Memo field database field name. <expL1> - .F. view only, .T. allow editing. <expC2> - Color for memo data. <expN5> - Maximum lines memo may contain. Default unlimited. <expL2> - .F. does nothing, .T. starts editing at the end of the memo text. Default .F. Description: The SHOW_MEMO procedure calls the Clipper EDITMEMO() function and provides a few small additional functions. It does not put a border or title on the screen. This procedure is called by the EDT_MEMO() function. If you want to use your own screen border and message line use this instead of EDT_MEMO(). See EDT_MEMO(), MEMFUNC() <90> The Aeolus Procedure and Function Library Reference Manual SHOW_TXT() Syntax: show_txt(<expC1>,<expN1>,<exp>,<expC2>,<expN2>,<expN3>, ; <expN4>[,<expC3>]) Pass: <expC1> - Alias name of database for SEEK. <expN1> - Index order number of <expC1> for SEEK. <exp> - Key expression for SEEK. <expC2> - Screen display expression. <expN2> - Screen row coordinate for display. <expN3> - Screen column coordinate for display. <expN4> - Rightmost screen column to display. <expC3> - Alternate color choice for display, default is WMSG_CLR Returns: A logical value. Description: The SHOW_TXT() function is very useful VALID function that sim- ply puts text on the screen after a user moves past the field where the SHOW_TXT() VALID is located. Sample: Suppose you have a database for customer purchases and one of the fields in this database is a Part Number. This represents the item your customer has purchased. When the Part Number is keyed you would like to display the Part Description that corre- sponds to the Part Number. The SHOW_TXT() VALID function can do this in the following manner: Technical assumptions: The customer database is called CUSTOMER and contains a five byte character field called PART_NBR which contains the Part Number the customer purchased. The look up table database with the part descriptions is called PARTS and index order one (1) is on the PART_NBR field. The PARTS database part description field is called PART_DESC. . . . ** add the ISEEK/MESSAGE to have the display of the ** Part Description on PgUp's and PgDn's ** iseek(qpart_nbr,"PARTS",1,.f.) message(parts->part_desc,dr1+10,dc1+2,dc1+32,wmsg_clr) <91> The Aeolus Procedure and Function Library Reference Manual ** @ dr1+09,dc1+16 get qpart_nbr pict "!!!!!" valid ; show_txt("PARTS",1,qpart_nbr,parts->part_desc, ; dr1+10,dc1+2,dc1+32) . . <92> The Aeolus Procedure and Function Library Reference Manual TEXTVIEW Syntax: do textview with <expN1>,<expN2>,<expN3>,<expN4>,<expC1> ; [,<expL>][,<expC2>] Pass: <expN1> - Top row screen coordinate. <expN2> - Left column screen coordinate. <expN3> - Bottom row screen coordinate. <expN4> - Right column screen coordinate. <expC1> - Name of a CR/LF delimited text file, include the extension. <expL> - Print key enable/disable. Pass .T. to enable or .F. to disable. Default is disabled. <expC2> - Name of a user defined function to program alternate keystrokes and use TEXTVIEW passed parameters. Description: The TEXTVIEW function simply displays a CR/LF (carriage return /line feed) delimited text file within the passed screen coordi- nates, <expN1> through <expN4>. The advantage of this function over the EDITMEMO() function provided by Clipper is that TEXT- VIEW can view any size file whereas EDITMEMO() is restricted to a maximum of 64K. TEXTVIEW does not read the whole file into memory, only the portion of the file currently displayed is in memory, so TEXTVIEW uses very little of the programs available memory. Passing <expC2> the programmer can customize TEXTVIEW by examin- ing the parameters passed and writing custom routines for view- ing text files. The parameters passed to the UDF are: <expN1> - The leftmost column of the file currently being displayed. <expC> - The status of TEXTVIEW when the UDF was called: "BF" - Beginning of File. "EF" - End of File. "BP" - Beginning to Print. "EP" - End of Print. <expN2> - Length of the longest record in the current display window. <expN3> - INKEY() value of the last key pressed. <expN4> - The file handle of the text file being viewed. The return value from the UDF MUST be a logical value, if your function returns true (.T.) then the screen will be refreshed. If your function returns false (.F.) then the screen will not be <93> The Aeolus Procedure and Function Library Reference Manual changed. Sample: A TEXTVIEW call with a UDF to display a report file. . . . set colo to (wndw_clr) winpush(dr1,dc1,dr2,dc2) message("▓ "+chr(27)+chr(26)+"/TAB/Shft+TAB/"+chr(24)+chr(25)+ ; "/PgUp/PgDn/Home/End-Scroll ▓ Alt+P-Print ▓ ESC-Exit ▓", ; msg_ln,00,80,msg_clr) @ dr1,dc2-12 say chr(181)+"REPORT.TXT"+chr(198) set colo to (wmsg_clr) do textview with dr1+1,dc1+1,dr2-1,dc2-1,"REPORT.TXT",.t.,"TEXTFUNC" set colo to (wndw_clr) winpop() ********************************************************************* ** Example function called by TEXTVIEW text file viewer with examples ** of how to use the passed parameters. ********************************************************************* func textfunc para tcol,tstat,twdth,tkey,thndl ********************************************************************* ** TCOL - Leftmost column position in the current display window. ** TSTAT - BF-Beginning of File; EF-End of File; BP-Begin of Print; ** EP-End of Print; or nul if no status to report. ** TWDTH - Character width of the widest record in the current ** display window. ** TKEY - INKEY() value of the last key pressed. Use TKEY to ** program your own keystrokes during a TEXTVIEW. ** THNDL - File handle of file being viewed. ********************************************************************* ** check all status conditions and display result set colo to (wndw_clr) do case case tstat="BF" @ dr1,dc1+1 say chr(181)+"TOP"+chr(198) case tstat="EF" @ dr1,dc1+1 say chr(181)+"BOT"+chr(198) case tstat="BP" tfoc=setcolor() set colo to ("*"+tfoc) @ dr1,dc1+2 say "PRT" set colo to (tfoc) case tstat="EP" @ dr1,dc1+1 say chr(181)+" "+chr(198) <94> The Aeolus Procedure and Function Library Reference Manual otherwise @ dr1,dc1+1 say chr(181)+" "+chr(198) endc ** display left/right helper arrows if needed if tcol>1 @ dr2,dc1 say chr(27) else @ dr2,dc1 say chr(200) endi if tcol+(dc2-dc1)-2<twdth @ dr2,dc2 say chr(26) else @ dr2,dc2 say chr(188) endi set colo to (wmsg_clr) ** Trap CTRL+HOME key and make it do the same thing as ** the HOME key. if tkey=29 && INKEY() value of Ctrl+Home fseek(thndl,0,0) && go to the beginning of the file tcol=0 && set left column also retu(.f.) && make TEXTVIEW redisplay window endi retu(.f.) && no need to redisplay the window <95> The Aeolus Procedure and Function Library Reference Manual THERMOMETR() Syntax: thermometr(<expN1>,<expN2>,<expN3>,<expN4>) Pass: <expN1> thermometer length <expN2> start value of operation (i.e. 0%) <expN3> maximum value of operation (i.e. 100%) <expN4> current value, must be between <expN2> and <expN3> Returns: a character expression. Description: The THERMOMETR() function is used to display the progress of iterative program activity graphically. The <expN1> argument is the length you want your thermometer, <expN2> is the number of the starting position of your process, <expN3> is the ending position and <expN4> is the current position. Sample: *************************************************************** ** THERMOMETR() function example ** select trnsctn go top strt=1 end=reccount() width=40 othm=" " && old thermometer for comparison do whil !eof() thm=thermometr(width,strt,end,recno()) if thm <> othm && only display changes @ 1,0 say thm othm=thm endi . . . skip endd <96> The Aeolus Procedure and Function Library Reference Manual TIMEOUT Syntax: call timeout with <expB1>,<expB2>,<expC> Pass: <expB1> - Computer idle time in seconds. <expB2> - Keyboard scan code to put in keyboard buffer on a timeout condition. <expC> - one byte or longer character memory variable set to any value other than "Y". Returns: Nothing Description: The TIMEOUT assembly subroutine tests the computer's keyboard, disk(s), serial port, video interface, and printer port(s) for activity. If no activity has occurred and one (1) second has passed, an internal variable is incremented. If any activity whatsoever occurs on the computer the internal variable is set to zero. If the subroutine's internal variable counter reaches the value passed as <expB1> then <expB2> is put in the keyboard buffer as if the key was pressed on the keyboard and the Clipper memory variable passed as <expC> is set to "Y". So if the computer is completely idle (i.e. NO ACTIVITY AT ALL) for <expB1> seconds then <expC> is set to "Y" and <expB2> is put in the keyboard buffer. Note also that TIMEOUT will change the cursor between an under- line and a block when the insert key is pressed. WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING TIMEOUT CANNOT (!) BE USED IN AN OVERLAY. IT TAKES OVER SYSTEM INTERRUPTS. IF PUT IN AN OVERLAY, YOUR COMPUTER WILL (WILL !!) CRASH. WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING*WARNING It is up the Clipper program to be set up to deal with these conditions. See the following example and also see the program source for TTEST.PRG included in the BUILDER package. . . . set key 259 to tmout_xit && Ctrl+2 INKEY() value idle_var="N" readinsert(.f.) <97> The Aeolus Procedure and Function Library Reference Manual ** Clipper program to time out after one hour (3600 seconds) ** ** Hex 0300 is the keyboard scan code for Ctrl+2 ** call timeout with l2bin(3600),l2bin(hex2dec("0300")),idle_var . . . . ** Proc executed on every press of Ctrl+2 ** if IDLE_VAR="Y" then the program timed out, so set errorlevel ** and exit. ** proc tmout_xit para prc,lin,var if idle_var<>"Y" return endif set cursor on set colo to w/n errorlevel(1) clea quit Use the following table to find keyboard scan codes: TIMEOUT Keyboard Scan Codes Key Normal Shifted w/Ctrl w/Alt A 1E61 1E41 1E01 1E00 B 3062 3042 3002 3000 C 2E63 2E42 2E03 2E00 D 2064 2044 2004 2000 E 1265 1245 1205 1200 F 2166 2146 2106 2100 G 2267 2247 2207 2200 H 2368 2348 2308 2300 I 1769 1749 1709 1700 J 246A 244A 240A 2400 K 256B 254B 250B 2500 L 266C 264C 260C 2600 M 326D 324D 320D 3200 N 316E 314E 310E 3100 O 186F 184F 180F 1800 P 1970 1950 1910 1900 Q 1071 1051 1011 1000 <98> The Aeolus Procedure and Function Library Reference Manual TIMEOUT Keyboard Scan Codes Key Normal Shifted w/Ctrl w/Alt R 1372 1352 1312 1300 S 1F73 1F53 1F13 1F00 T 1474 1454 1414 1400 U 1675 1655 1615 1600 V 2F76 2F56 2F16 2F00 W 1177 1157 1117 1100 X 2D78 2D58 2D18 2D00 Y 1579 1559 1519 1500 Z 2C7A 2C5A 2C1A 2C00 1 0231 0221 7800 2 0332 0340 0300 7900 3 0433 0423 7A00 4 0534 0524 7B00 5 0635 0625 7C00 6 0736 075E 071E 7D00 7 0837 0826 7E00 8 0938 092A 7F00 9 0A39 0A28 8000 0 0B30 0B29 8100 - 0C2D 0C5F 0C1F 8200 = 0D3D 0D2B 8300 [ 1A5B 1A7B 1A1B 1A00 ] 1B5D 1B7D 1B1D 1B00 273B 273A 2700 ' 2827 2822 ` 2960 297E \ 2B5C 2B7C 2B1C 2600 (same as Alt L) , 332C 333C . 342E 343E / 352F 353F F1 3B00 5400 5E00 6800 F2 3C00 5500 5F00 6900 F3 3D00 5600 6000 6A00 F4 3E00 5700 6100 6B00 F5 3F00 5800 6200 6C00 F6 4000 5900 6300 6D00 F7 4100 5A00 6400 6E00 F8 4200 5B00 6500 6F00 F9 4300 5C00 6600 7000 F10 4400 5D00 6700 7100 F11 8500 8700 8900 8B00 F12 8600 8800 8A00 8C00 <99> The Aeolus Procedure and Function Library Reference Manual TIMEOUT Keyboard Scan Codes Key Normal Shifted w/Ctrl w/Alt BackSpace 0E08 0E08 0E7F 0E00 Del 5300 532E 9300 A300 Down Arrow 5000 5032 9100 A000 End 4F00 4F31 7500 9F00 Enter 1C0D 1C0D 1C0A A600 Esc 011B 011B 011B 0100 Home 4700 4737 7700 9700 Ins 5200 5230 9200 A200 Keypad 5 4C35 8F00 Keypad * 372A 9600 3700 Keypad - 4A2D 4A2D 8E00 4A00 Keypad + 4E2B 4E2B 4E00 Keypad / 352F 352F 9500 A400 Left Arrow 4B00 4B34 7300 9B00 PgDn 5100 5133 7600 A100 PgUp 4900 4939 8400 9900 PrtSc 7200 Right Arrow 4D00 4D36 7400 9D00 SpaceBar 3920 3920 3920 3920 Tab 0F09 0F00 9400 A500 Up Arrow 4800 4838 8D00 9800 - Some key combinations are not available on all systems. The PS/2 includes many that aren't available on the PC, XT and AT. <100> The Aeolus Procedure and Function Library Reference Manual TOTALKEYON/TOTALKEYOFF Syntax: do totalkeyon do totalkeyoff Description: Sets up the left and right arrow keys to jump from one drop down menu to the menu under the right or left. Comment: The BUILDER program creates the source with TOTALKEYON and TOTALKEYOFF already called at the proper places and you should not need to use this procedure. <101> The Aeolus Procedure and Function Library Reference Manual WAITKEY() Syntax: waitkey([<expN>]) Pass: <expN> timeout seconds Returns: a numeric expression. Description: Use WAITKEY() as a substitute for the Clipper INKEY(<expN>) function. The only difference between the two is that WAITKEY() will react to any SET KEY TO ... 's you have set. Not passing the parameter or passing zero (the default) will cause WAITKEY() to wait until a key is pressed with no timeout. <102> The Aeolus Procedure and Function Library Reference Manual WINPOP() Syntax: winpop() Pass: Nothing Returns: A logical value, true if there was something removed from the screen. Description: The WINPOP() function removes the last window on the screen that was created by the WINPUSH function. See WINPUSH() for examples. <103> The Aeolus Procedure and Function Library Reference Manual WINPUSH() Syntax: winpush(<expN1>,<expN2>,<expN3>,<expN4>[,<expL1>] ; [,<expL2>][,<expL3>][,<expL4>]) Pass: <expN1> top left row <expN2> top left column <expN3> bottom right row <expN4> bottom right column <expL1> save the screen area before displaying, default true <expL2> clear the interior of the box, default true <expL3> display the box with a border, default true <expL4> display the box with a shadow, default true Returns: A logical value, if the window was successfully displayed, true is returned. Description: The WINPUSH function saves the portion of the screen bounded the coordinates <expN1> through <expN4> with <expN1> and <expN2> being the upper left row and column positions and <expN3> and <expN4> the lower right corner positions and draws a box on the screen in the default color. All four of the logical expressions that can optionally be passed have a default value of true. If <expL1> is true the screen area bounded by the passed screen coordinates is saved to the screen array otherwise if set to false it cannot be WINPOPed. <expL2> if set to true will clear the box interior otherwise only the border, if any, is displayed. The default it true. <expL3> if set to true will display a double border on the box. <expL4> controls the shadow on the box, if set to true a shadow is displayed. Note: If the variable XPLODE is a logical variable set to true the WINPUSH function will explode the window onto the screen. Sample: ************************************************************** *** WINPUSH/WINPOP sample code *** ** put a window on the screen ** saving the area so it can be WINPOPed, <104> The Aeolus Procedure and Function Library Reference Manual ** clearing the inside of the window when displayed, ** put double border characters on the window, ** and put a shadow on the window. winpush(05,10,17,60) @ 07,12 say "My Window to the World." inkey(0) ** remove window, and shadow. winpop() <105>